Asema IoT Central

User Manual


Chapter 1. Introduction

The Asema IoT Central is a versatile system integration software for Internet of Things projects. It is designed to be an efficient tool that scales without effort from simple one machine data logging applications to heavy-duty service oriented cloud architectures. Unlike the majority of IoT solutions that rely on a heavy middleware architecture, Asema IoT Central is one extendable modular application. The lightweight approach enables running it much more efficiently, with less hardware requirements, easier maintenance, and native capability for edge computing.

Asema IoT Central is meant to serve as a basis for custom application building. The software comes with a range of pre-developed applications that can be used straight out of the box for sensor monitoring, remote control dashboards, product pricing, information displays, etc. The source for all these applications is also included, making it possible to modify, extend and expand them from simple re-branding to full-blown logic customization. We however deliberately want to avoid calling Asema IoT Central a "platform" as that would give the common impression of a heavy system with lengthy development cycles and advanced installation. Asema IoT Central is a solution, not a platform.

The difference between a lightweight, optimized system and a middleware-driven solution is significant: where a Java middleware driven IoT solution easily can take 20-30GB of disk space and require a multicore processor with several gigs of memory, Asema IoT Central with all cloud bells and whistles packs in just under 200MB of disk. It can run with less than 100MB of RAM with full user interface and a mere 12MB in the headless mode that is typical for server installations. A stripped down edge version, Asema IoT Edge, takes about 50MB of disk and runs on a single core embedded ARM taking less than 5MB of RAM. This makes it possible to run sophisticated applications in the form of a grid by installing the system as autonomous instances into inexpensive embedded boxes such as Raspberry Pi or Android and iOS mobile devices. For someone that hosts sensitive data for multiple customers it means direct cost savings: if each customer demands their own virtual machine, the specs of that virtual machine can be minimal, resulting in clearly lower operating costs. For instance, an IoT system running on Java Tomcat server takes about 1.5 gigs of memory to run smoothly. You can have over 100 Asema IoT Central installations running within the same memory space, with equivalent functionality.

Small and efficient does not mean less powerful. Integral to the design of the software is the idea of networked entities that can flexibly connect to each other to create a grid of nodes that perform distributed tasks in the system. While this not only allows for better scalability, it also offers a solution to the common problem of connected business applications, namely who owns the data and where data should be located. As there is no requirement for a central cloud to store data, access to data can be set by location and then shared with access rights either temporarily or permanently. Chinese walls can be established for security simply by giving each client their own instance of the Asema IoT Central in their own sandboxed environment, removing the possibility that the data of various clients could somehow be mixed up.

Asema IoT Central integrates into one solution all components needed to very easily set up a data logging and visualization environment. It not only has the required connections to databases and visualization libraries but even embeds a full blown web browser within itself. This integration gives unparallelled control of the visualization logic, including tweaking the visualization engine itself. This allows for integration of old and new visuals, e.g. an existing web application, as layers and objects. For instance one could take an existing corporate intranet site and overlay measurement data on top of it to create new visuals with absolutely no changes to the old intranet site.

Significant effort has been put into the easy deployment of the system and the applications it runs. Asema IoT Central features its own Screenlet Store, an equivalent of an app store that allows distributing IoT applications easily online. Apps can be shared between two deployments, a group of software installations or the whole user community. Automatic setup and configuration a new instance is easy: just run the setup program and type in the password for the deployment group. Network connections, security settings and applications will be set up automatically.

As an IoT central component, Asema IoT Central embeds into it support for the latest database and networking technologies. It connects to both traditional relational databases and modern NoSQL databases. It can act as both a client and a server to sensors, actuators and cloud platforms, either over industry standard network protocols such as HTTP, MQTT and CoAP or directly with a local wireless or wired connection using WiFi, Bluetooth and Bluetooth Smart.

Chapter 2. Main features

Asema IoT system is a powerful tool for building and managing a network of resources, whatever these resources are — shared city bikes, solar panels, microturbines, motors, weather monitoring systems and many more. With Asema IoT system, you can:

  • Create large remote-operated networks of physical devices and logical resources.

    Asema IoT Central allows you to connect to a range of heterogeneous remote resources, whether those may be a kitchen kettle, a light bulb, a database or a full remote cloud system. You can easily deploy thousands of field units and connect to them.

  • Monitor and control the resources in the network.

    With Asema IoT Central you can monitor connected resources and control them remotely (switch on or off, or change their properties). The controls can be automated with automation rules and scripting. Prediction and optimization routines offer advanced means for driving the resources with automation at optimal periods.

  • Build custom desktop, mobile and web applications.

    The application management tools, APIs and components let you create IoT applications with custom look & feel and domain specific logic. These applications will run natively on mobile devices and PCs. The underlying components take automatically care of complex implementation issues such as security, data synchronization, and connection management.

  • Trade with resources.

    With the sharing functionality of Asema IoT Central you can publish your resources over a secure, trading enabled API to other systems. Customizable pricing models make it possible to create storefronts and Point-of-Sale systems where users can interact and purchase features and functionality directly from a touchscreen. NFC compatibility makes it possible to pay with various key fobs and smart cards.

  • Visualize the data and report results.

    Asema IoT Central's graphical interface includes a range of ready-made controls, graphs, and other visual elements to display data. You can fully customize the visuals, rebrand them as desired and publish the data in both mobile native and web browser interfaces. Customizable PDF reports and templates as well as email integration make it possible to automatically create and distribute reports of system status.

While offering a very fast setup time for straightforward control applications, Asema IoT Central has been designed to work in complex, distributes environments where multiple inputs and environmental factors need to be taken into account when driving advanced automation. A prime example of such an environment is the management of renewable energy. Here, the main concern is ensuring the reliability of energy supply while at the same time maximizing the production by using unreliable sources such as wind and solar power. To illustrate the Asema IoT Central's features in such an environment, let's take an example use case. Imagine an energy company sells locally generated renewable energy to houses. The sources of energy supply in such a setting are typically threefold. First, there is some local generation in the form of a wind turbine, a solar panel or a generator driven with biogas. Second, to ensure even supply, the generated energy has a local storage in the form of a battery as well as a connection to the electricity grid from where the system can draw reserve power. third, if the number of customers is large, some customers may also be willing to act as a reserve pool, willing to reduce their energy use at peak hours (i.e. they are offering so called "negawatthours").

The optimization problem of the energy company is which source of energy to use at each point in time. Should the supplied power be taken from the battery, from the generators, from the grid or as negative consumption by the residents? Each of these has both some price and some lag. Therefore the optimization must calculate a schedule for each source based on forecasts of usage and production as well as a forecasted cost of each component.

Asema IoT Central has been designed to work as a central coordination hub in such a scenario. It contains the logic needed both to make the calculations and to perform the automation. Sharing features take care of the bookkeeping of transactions and the embedded and edge versions of the software can be installed in premises as control gateways when needed.

Chapter 3. About the system

As a central hub for one or several Internet of Things applications, Asema IoT monitors and controls remote units, analyzes their performance, combines the data with other data sources, and much more. A remote unit can be virtually anything: a device such as a light bulb or a sensor, a piece of hardware such as a Raspberry Pi, a database, a web service, or a software application.

Depending on the nature of the unit, Asema IoT Central offers certain ways to connect to it. For example, direct IP connection to a hardware unit, a cable or wireless connection to receive serial data, or an HTTP API connection to fetch data from a server.

Such connections can be diverse and use several different protocols. The role of Asema IoT Central is to simplify this access by unifying the data model an offering one consistent approach to automation and applications no matter what the connection is. To understand how this is done, there are three primary concepts one should be familiar with: objects, pools, and applications.

3.1. Objects and schemas

Central to the philosophy of an Asema IoT system is the concept of an object. An object in Asema IoT is anything that can be represented as a single source of data or something to control. The granularity of such definitions depends on the application. So, for instance in a system that monitors the movement of cars, each car would be an object. In a telematics system that controls a single car, each monitored part such as the engine, the air conditioning and the steering could be an individual object.

An object is used to store the data and handle all operations related to this unit. This data can be stored into two types of object parameters:

  • Metadata. Metadata is read-only data that describes an object. Metadata is assumed to remain constant and does not have a history. For instance, in the case of cars, the name of the manufacturer would be metadata. Because metadata is supposed to remain constant, no device control can be achieved by changing metadata.

  • Properties. Properties are read-write items that are assumed to change over the course of time. Their history can be stored into a database and their values can be altered. Changes in properties propagate to drivers which then cause controls in actual physical devices to take place. Again, in the case of cars, the speed of the car would be modeled as a property. Changing the value of this property would cause the car to accelerate or decelerate.

Typical tasks of IoT, such as monitoring a value or turning a switch on or off, are performed by reading and writing the properties. When a property changes, this event in turn activates some application-specific driver that makes the action happen in real life.

What data an object actually contains is defined with a schema. A metadata schema tells what type of metadata to attach to the object. Similarly, a property schema defines what type of properties the object has. In addition to defining the data fields, a schema also acts as a definition file that tells how to retrieve the property values from some data flow which in turn originates from a hardware device or other data source. Further, the schema defines how to convert the data into common format, what authentication is required to receive the data, an so on.

With the schema definitions and property values, the objects effectively create a virtual copy or representation of a physical object. When this virtual object is modified, the Asema IoT system ensures that the modifications are then reflected in the actual physical object. The virtual copy concept allows for ensuring reliability of controls as the values can be tracked and rewritten in case of malfunction or connection problems. This process is called "shadowing". The virtual copy acts as a shadow of the physical object and will maintain that shadow state when needed. If a connection is lost while controlling a unit, the shadow will reattempt writing the controls and will do so once the connection is re-established.

For more information about objects and how to set them up, see 6, Object connectivity.

3.2. Pooling and sharing

In many cases, there's a need for one IoT system to access resources of another IoT system. For example, the energy company buying excess electricity from solar panels might need to add these solar panels to the list of energy sources in their system. This can be done in two different ways:

  • Pooling

    A pool is the collection of all objects in one particular Asema IoT system. The pool contains all the virtual objects that the system has and can be queried by APIs and applications to get access to those objects. Pools offer the programming interfaces needed by applications and other logic to perform the actual functionality of a particular feature set. So in essence, pools are the link between IoT devices and IoT applications.

    Objects and their data can be accessed by external systems by combining pools. That gives you an opportunity to add objects from another Asema IoT instances or other standard compliant systems to your pool of objects.

  • Sharing.

    Sharing is opening access to particular object(s) from your pool via API. Unlike pooling, sharing enables you to require payment for the actions performed with shared objects, for example, for unlocking a rented bike.

For more information, see 7, Connecting several IoT systems together and 8, Sharing.

3.3. Applications

While the desktop and web interfaces offer comprehensive tools for managing and monitoring objects, more often than not an IoT system is required to have its own application logic and look and feel. For this purpose you can also create your own applications with custom features and interface instead of using ready-made interface options. Customization can be simple branding or just adding some additional data to the raw IoT data, for example, you can add a news feed, or messaging, or stream a video to the user screen. Or the custom application can be a very comprehensive individual web service with fully custom front end and backend logic. Both of these can be achieved in Asema IoT with custom applications.

Asema IoT offers three different programmable user interface methods to the system:

  • Screenlets

    These are graphical desktop and mobile applications for Asema IoT. Screenlets can be used to augment the current functionality, create new compelling services, or to just change how the device software looks like. If you want to create native mabile or desktop applications, screenlets is usually the best choice.

    For more information, see 12.2, “Screenlets”.

  • Web applications

    Asema IoT software includes a set of JavaScript libraries that make it convenient to communicate with the backend system, load objects to control, and to react to various events and measurements. These libraries plug into web development frameworks, making them the tool of choice for browser applications.

    For more information, see 12.1, “Web applications”.

  • PDF and spreadsheet reports

    These are static reports that are exported from the system and can be used to analyze data with spreadsheets, attach system status to reporting emails, etc. Note that while the resulting report is static, its construction can be fully programmed and customized. So if you're looking for applications with reporting and documentation capabilitirs, then these dynamic reports is the way to go.

    For more information, see 13, Generating reports.

In addition to programming application logic into the applications themselves, you can add logic into the backend. Backend implementation has the benefit of running irrespective of whether an application is active and it is shared across applications.

Application backend logic runs in the form of business rules in the Rule Engine and request processors in the Script Engine. The Rule Engine lets you configure automated control of the objects by creating various logical rules which trigger once conditions are met. For example, you can make a rule that says: "If the temperature in the room falls under 20 degrees, turn on the heating". You can compose simple rules from ready-made blocks or program custom rules that contain more complex logic. The Script Engine on the other hand does processing of data when some application requests it. It is similar to server side logic you find in most web application servers.

Note

There may be other concepts and terms in this manual that are specific to Asema IoT and therefore unknown to the reader. For a quick reference of the vocabulary used in this manual, please refer to 21, Vocabulary and concepts.

Chapter 4. Installation and startup

Asema IoT Central can be installed on Windows, macOS and Linux. In all of the operating systems it can run as a desktop or a server/ cloud application and offers two interfaces to the system: the desktop interface and the web interface.

The desktop application provides graphical interface to display information and run end user applications on a PC screen. While it has comprehensive tools for maintaining and controlling the applications, desktop interface contains only basic system setup for connecting and syncing the application. For system setup functionality, the web interface should be used. The web interface can be opened in all installations by accessing the Asema IoT Central with a browser.

The web interface features all setup tools needed to configure the system. It also has a configurable control dashboard for managing and monitoring objects. On a server/ cloud where there is no display, the web interface is naturally the only interface available. To avoid pointing to a non-existant display, the cloud system should be started in the so called headless mode which does not try to access the display.

Note

On a desktop, the system can also be started in the headless mode i.e. without any graphical interface if so desired.

In addition to the Asema IoT Central desktop or server/ cloud installation, you can use the Asema IoT Dashboard mobile app for Android and iOS mobile devices. The app features the same user interface technology as the graphical desktop interface of Asema IoT Central. So these two are equivalent combinations:

  • Asema IoT Central desktop installation with admin interface and graphical interface

  • Asema IoT Central cloud installation with admin interface and Asema IoT Dashboard on a mobile device.

4.1. Licenses

As commercial software, Asema IoT Central requires a license to run it. At first installation, the system will obtain a demo license which is a limited time license bound to the PC where the system is installed.

The demo version of Asema IoT Central can be used for 30 days without a license. After that, you need to register the software and obtain a license. For the license options, including a free license, visit https://licenses.asema.com.

You don't need a license to use the Asema IoT Dashboard mobile app.

4.1.1. Obtaining a license

To obtain a license, go to System > About and license in the Asema IoT Central's web interface. Generate a license token, copy it and enter at https://licenses.asema.com.

If the token you enter matches the token in the software, you will be offered the options that apply to the particular version of the software you use. Once the request has been processed, restart Asema IoT Central and the license will be upgraded automatically.

4.2. Installing Asema IoT Central

To install Asema IoT Central, obtain the corresponding installation package and start the installer as described in the following sections.

Important

Remember to install the package that fits the type of your operating system. If you are running a 32-bit system, you need the 32-bit installer. A 64-bit operating system can run both 32-bit and 64-bit software. Unless you are running an embedded system, 32-bit systems are very rare. So the 64-bit should nearly always be the correct choice.

4.2.1. Windows

Asema IoT Central for Windows is distributed as an .msi package. To install the software, double-click the installer, then follow the on-screen instructions.

4.2.2. macOS

Asema IoT Central for macOS (Mac) is available as a .dmg package. To install the package, double-click it to open. Then drag the software icon into the Applications folder.

4.2.3. Linux

Asema IoT Central for Linux is distributed in .rpm packages. The installation process differs depending on the Linux distribution you use. In most distributions it is enough to double-click the RPM package and then follow instructions on screen..

To install the .rpm from command line, run the following command as root: rpm -Uhv asema_iot_central_for_linux.rpm

4.3. How to run Asema IoT Central

You can run Asema IoT Central as a desktop application or a server/cloud application. The functionality in both is the same, with the exception that on a server you usually cannot use a graphical user interface as a display is missing. In this case, the most appropriate way to run the system is in headless mode and log in with the browser admin interface.

4.3.1. Desktop application

When you setup the system with the installer on Windows or macOS, it creates an application icon. To run Asema IoT Central with a user interface for a desktop application, click/ double-click this icon. On a Linux, open a terminal window and type asema_iot_central_linux.sh to start. Then follow the welcome wizard instructions to complete the system setup.

4.3.2. Cloud server

Start the system from the command line. The program binary is located in the /bin of the installation directory you gave to the installer. Run the program in headless mode using the -h flag. For example:

On a Linux: bin/asema_iot_central_linux -h

On macOS: bin/asema_iot_central_mac -h

On Windows: bin/asema_iot_central_windows.exe -h

Note

If you try to start the application with the graphical user interface through a shell session at a remote server, you're likely to get an error concerning a missing display. This is because a shell does not have a display. To run the application, use the headless mode and then access it through the web admin interface.

4.3.3. Logging in to the admin interface

Asema IoT Central features two interfaces: the graphical local interface and the admin interface. The graphical interface is only available if you start the system as a desktop application. It is a customizable UI for displaying information and for end user applications. It contains only rudimentary basic system setup for connecting and syncing the application but not the actual administration features. For admin features that let you define most of the features and functionality, you need to login to the admin interface.

The admin interface is available for all installations, whether you start the system as headless or not. It lets you remotely configure and monitor cloud installations also.

Once you started the software, you can login as admin. By default, the system runs on port 8080 on your server. To login, open a browser and enter the following URL: http://[ip or domain of your server]:8080. For example, to access the system on localhost, use the url http://127.0.0.1:8080

The default user is admin and the default password is admin

Note

Remember that the server where you have installed Asema IoT most likely has a firewall. If you access the admin interface from a remote machine, remember to open port 8080 (TCP) from the firewall.

Important

Change the default admin password in the Users menu as soon as you log in to the system to avoid security breaches.

4.3.4. Connect with a mobile app

Asema IoT Dashboard is the free mobile app for using Asema IoT with an Android or iOS device. You can install Asema IoT Dashboard from the Android or iOS App Store (Google Play or Apple App Store). Asema IoT Dashboard runs the same screenlet applications as Asema IoT Central and takes care that data is synced automatically so that the user experience is the same irrespective of whether you have a local desktop connection or a remote connection.

Once installed, you can connect Asema IoT Dashboard software with your Asema IoT Central installation. A setup wizard will help you in the process when the application starts.

Note that Asema IoT Dashboard can connect to several Asema IoT Centrals simultaneously if necessary. The connection is set up from the mobile app. Note that because your Asema IoT Central may be running in a local network behind a firewall, there are several ways in which this connection can take place:

  • Direct remote access if you are running Asema IoT Central on a server with a public IP address.

  • Direct local access if you are running Asema IoT Central within a local network andyour mobile device is connected to the same local network. Note that connections from outside the network are not possible in this case.
  • Routed remote access to Asema IoT Central by using CloudRoute VPN groups if you are running Asema IoT Central within a local network but your mobile device is not in the same network (uses a 4G connection for instance).

For a direct remote access to a public IP, simply enter the IP address or domain name of your server to the connection settings of the mobile app.

For local access, you can either enter the IP address of your server to the connection settings of the mobile app (if you know the address) or let the mobile app scan your local network. After scanning, choose the found software instance.

For routed remote access, create a VPN group in case you haven't created one yet. In the web admin interface of Asema IoT Central, go to System > Memberships. Create a group by giving it a group name, username and password. Then in the connectivity settings of Asema IoT Dashboard, enter the same details. The members of the group will be displayed. Choose the Asema IoT Central instance from the group to connect the mobile app to it.

Chapter 5. System settings

System settings can be found under the System menu of Asema IoT Central web admin interface. Most settings related to configuring and maintaining the system and setting up the services are located here.

5.1. Paths and identifiers

When you manage a large system and need to install components, take backups, connect to APIs, an so on, it is easy to forget where exactly the necessary files are and how the network was configured. Worry not, Asema IoT instances summarize all of them for you. In the System > Paths and identifiers section, you can find all URLs and locations you need for configuring the system and using APIs.

5.2. Basic details

Basic details of your system are needed to access Smart API (i.e. sharing functionality) and display information in the Smart API Find registry where other users search for offers.

5.3. Notification broker

Asema IoT Central supports MQTT as a protocol for communication between various software instances. Asema IoT Central itself can act in all roles of MQTT communication:

  • A broker. The role of the broker is to pass messages between subscribers and publishers.

  • A subscriber. In this case, Asema IoT is a notification listener that listens to certain topics at the broker and passes that data to corresponding objects.

  • A publisher. In this role, Asema IoT is a notification sender that publishes data about objects through the broker to one or multiple subscribers.

The Notification broker status screen in system settings shows you the current status of the broker in its current operating mode.

If your Asema IoT Central is set up to act as an MQTT message broker, the list of topics that have been subscribed to are shown in the System > Notification broker section.

Note that in MQTT, there is no further need to configure the broker. Currently Asema IoT Central doesn't support private MQTT channels or authentication. It will simply match the topics between publishers and subscribers and pass the messages between them.

5.4. Notification listener

Asema IoT supports MQTT as a protocol for communication between various software instances. Asema IoT Edge itself can act as a notification listener or as a notification sender.

As a notification listener, Asema IoT listens to an MQTT topic and passes on that data to some object for processing. The topic can either be assigned to a particular object or you can have Asema IoT create an object on the fly as it receives a message.

To set up your Asema IoT application as a listener, go to System > Notification listener. Then add a topic by specifying:

  • Name of the topic.

  • Publisher ID, Publisher type, Conversation ID, Conversation type make up the topic path. You can replace any part of this path with the hash (#) wildcard character.

  • URL encode. You may choose to URL encode the topic to handle for instance forward slashes within the levels. By default the four parts of the topic are handled as four levels separated by a forward slash as is common in MQTT i.e. your topic will look like this: publisherID/publisherType/conversationID/conversationType. However, if any of these levels itself uses a forward slash, this will become a problem. You may for instance in Smart API applications need to use a Publisher ID that is a URI i.e. a string that starts with http://. This causes trouble as the forward slashes will mark it as two additional levels. Tick the URL encode option to encode each level so that forward slashed become %2F and pass through the broker without confusion.

  • Bind to schema that should be used for parsing the messages.

  • Autocreate an object for receiving the messages. It will appear in the list of objects.

Tick this box if you want to create an object automatically. Select a schema to bind it to. Without a schema, Asema IoT doesn't know how to process the data contained in the MQTT message.

Note

The schemas available in this menu are defined under Objects > Server API objects > API Schemas.

Leave the box unticked to assign the topic to a particular object. Define the topic here, then go to Objects > API objects and create or select an object. Choose MQTT as a protocol and then select the topic you've just created from the dropdown menu. Note that if you assign the topic to an object, the selection of the schema in system settings under Notification listener has no effect. The schema selected for the object in API objects is used instead.

5.5. Notification sender

Asema IoT can publish notifications about objects and about system events (system errors and warnings and changes in the geographic position of the system).

To set up your Asema IoT application as a publisher of system events, go to System > Notification sender. Add a broker server and enter topic names to send messages to.

To configure publishing notifications about objects, go to System > Notification sender and specify the broker server. Then go to Objects > Configure > Notifier and enter the notification settings there.

5.6. Object shadows

Object shadowing is a feature that prevents loss of data even if connection is broken. For each object in the system, Asema IoT Central creates a virtual copy (a shadow). The shadow is used to store the data sent to the object while it is disconnected. As soon as connection is back, the data stored in the shadow is sent to the object.

To configure shadowing, go to System > Object shadows. Then choose the time for which you want to keep the object shadow in the system. For example, if you choose "for one minute", a reconnected remote device will receive commands passed to the shadow up to one minute before the reconnection.

5.7. Peers and gateways

The Peers and gateways setup enables you to configure the remote pools of objects residing at peer systems (which may be full IoT platforms or hardware gateways such as embedded devices running Asema IoT Edge software). To connect to these pools of objects, go to System > Peers and gateways. To add objects of these remote pools to your own pool, click Setup and use one of the methods to find a peer or gateway:

  • Provide a username and password to a CloudRoute VPN group. The other members of the group will then be displayed for you to select.

  • Scan for compatible systems in your local IP network.

  • Enter the system's public URL or IP address.

You can use multiple methods simultaneously to select the combination of peers you desire. Once you finish the setup, the connections to these peers are made automatically. Objects from the pools will appear in your Objects menu once the connection is established.

For more information about object pools, see 7, Connecting several IoT systems together.

5.8. CloudRoute VPN

CloudRoute VPN is a VPN solution that connects CloudRoute compatible systems together over an encrypted Virtual Private Network. It secures traffic and makes it possible to directly communicate between systems even when they sit in separate private networks behind a firewall. CouldRoute VPN access is group-based. All systems that belong to the same group see each other and can communicate with each other. Access to a group is granted with a username and a password. Note that the username and password only give access to the VPN tunnel i.e. it establishes a connection to a remote system but does not log in. A system in a group may require further login credentials to access its data.

CloudRoute can also be used to access the web admin interface of Asema IoT remotely. To do so, the admin must be enabled in Asema IoT and you need to login to asema.com management service with the username and password of the group.

Asema IoT can also act as a port forwarder service to some other known service (such as a database or remote shell) that resides on the same machine as Asema IoT. This can help, for instance, in remotely managing a full software infrastructure needed by an IoT application.

To access Asema IoT remotely via VPN, go to System > CloudRoute VPN and choose Enable CloudRoute VPN for remote admin.

To use your Asema IoT application as a VPN gateway to access other servers, go to System > CloudRoute VPN and enter comma-separated ports.

5.9. Smart API

Smart API is the key technology used by sharing. You need to complete the configuration steps in the System > Smart API section to enable sharing functionality.

To use the directory services and semantic data of Smart API, each system needs:

  • A unique identifier (the Smart API identifier) that identifies the system to other parties.
  • A username and a password that grant access to the services.
  • A public/private keypair to sign and encrypt messages.

If these mandatory settings have not been set up before, the setup will propose doing those with a wizard. Simply open the wizard and follow the on-screen instructions to fill in appropriate values.

After the wizard has run, you can edit the information, including disabling the regular registration to Smart API find directory, changing the username and password, and regenerating the keys. Note that you cannot change the Smart API identifier any more as that should serve as the unique identification of this system throughout its lifespan.

The setup also includes the addresses of the infrastructure servers of Smart API. These are set by default to the public addresses of the servers. If your organization runs separate, private instances of the same servers, their addresses can be configured here to replace the public ones.

5.10. Webserver

The web (HTTP) server is the main application protocol server Asema IoT uses for the web admin interface and the majority of the APIs of the system. To set up a web server for running Asema IoT, go to System > Webserver settings.

In the Webserver settings, you can configure where the files served by the webserver (most notably the Web applications) will be stored. Additionally you can set up the HTTP URL paths for three functions: public pages, server side scripts, and proxying.

  • Public pages. The address path determines from which path pages and web applications are available. For example, if the path is set to mypath, then a file "mypage.html" stored in the public pages filesystem path would be available at http://[asema iot address]/mypath/mypage.html. Simularly the webapp called "myapp" is at http://[asema iot address]/mypath/myapp/
  • Server side scripts. This is the path for accessing server side script logic. If you would program a script and set its request path to "myscript" and then set the Server side scripts base path to "applicationscripts", your script would be accessed at http://[asema iot address]/applicationscripts/myscript
  • Proxied calls. Asema IoT Centralcan act as a simple HTTP proxy and will relay the calls given to it to some external server. This feature is especially useful if you are making a web application that needs other web application servers such as node.js to run but do not want to install a separate proxy server. The address of the other server (server to be proxied to) is configured by setting it to Default proxy target server. So for example, if you set the procy target server to http://192.168.0.100:8080and the Proxied calls base path to "myproxy", all calls to http://[asema iot address]/myproxy/mypath/will be forwarded to http://192.168.0.100:8080/mypath.

Note

Note that the ports used by the HTTP server are configured in the Network servers section of the setup.

5.11. Network servers

To specify network servers for connecting to other Asema IoT systems, go to System > Network servers. Define the following settings:

Require valid credentials to access APIs — Whether APIs can be accessed without API key. If on, this setting overrides the options chosen in Sharing > Access control.

HTTP, CoAP, MQTT, WebSocket server ports — Ports for accessing your Asema IoT from inside the firewall.

HTTP, CoAP, MQTT, WebSocket NATted ports — Ports for accessing your Asema IoT application from outside the firewall.

5.12. Email

This section contains settings for the system internal email client. This client is used for instance for notifications and without proper email settings sending those notifications via email will not work.

To be able to send notifications, the client will need to know at least

  • The address of the server for email sending (SMTP address)
  • The TCP port open in the server for email sending (SMTP port)
  • Traffic encryption type used by the server (if applicable)
  • Authentication protocol used by the server (if applicable)
  • Authentication username and password used by the server (if the server requires authentication for sending)

In addition to server settings, you may also define the default sender email address, sender name and subject line of the message to be sent.

By default, the notification messages are empty (they have no content, only the subject line). If you want notification emails to have some additional content, you cna do this by creating a template under Email alert templates.

An email alert template has a name, a subject and message body. The name is used only for identifying a particular template when you set up a notification, it will not be a part of the actual message. The subject will replace the default subject.

The template body is simply the body of the message that is sent and will be copied to the message as such, with the exception of two special tags that can be included in the template: the tag {{ name }} will be replaced by the name of the property that caused the notification. The tag {{ value }} will be replaced by the value of that property.

Note

Configuring when emails are sent as notifications is a feature of the Rule engine. To add email notifications to a rule, read the Automation section.

5.13. Bluetooth

Asema IoT has in-built support for short range radio protocols such as Bluetooth or NFC. With these you can connect a compatible radio device directly into a PC running Asema IoT or have two instances of Asema IoT talk to each other wirelessly over Bluetooth.

To configure Bluetooth communication, you need to define a hardware object of Bluetooth type. The object will automatically try to connect over the Bluetooth adapter on that PC.

For this to happen, you need to tell the software which Bluetooth adapter to use as you may have several of them on the PC. To do so, go to System > Bluetooth and enter the MAC address of the Bluetooth adapter to use.

5.14. Database

Database settings let you set up the connection to a database to store collected data related to the objects in the system such as property values, tasks and events.

Asema IoT Central supports multiple database systems, both traditional SQL and newer NoSQL, including Postgresql, MySQL, Apache Cassandra, InfluxDB and MongoDb.

Settings for each database type differ somewhat, though in most cases you need to provide the address of the database server (localhost if running on the same machine) and access credentials.

To fill in the details, choose the appropriate database model you wish to use and fill in the fields.

To save your newly entered settings, first test the connection with the Test button. This ensures that the settings are correct and the system can rely on being able to store the data without problems.

Note

Each Asema IoT Central installation uses two databases: one for configuration and one for data. The configuration database is always a local SQLite database. Changing the settings in this setup has no effect on the configuration database, you can only configure the database for object data.

5.15. Credentials

Credentials are access tokens to some system, either IoT Central itself or some system IoT Central connects to. A typical credential is a username-password pair.

There are three types of credentials in the Asema IoT:

  • System credentials. System credentials limit access to the Asema IoT instance the credential is in. This type of credential gives access to your Asema IoT. The system credentials are API keys that must be added to the HTTP calls that are sent to the Asema IoT when accessing it using the JSON API.

  • Client credentials. This type of credential opens access from your Asema IoT. Note that the calls to other systems are done by Network client objects. To use these credentials, they need to be added to the schemas of those objects. For more details on how to write such schemas, please see 6.3.2.3, “Network client objects”. Note that client credentials can also be written as such directly into those schemas. However, this will expose the username and password to anyone who edits the schemas. To hide such details, put the credentials into system settings. They can then be deferred to in the schemas with their IDs.

  • Certificates.

5.16. Memberships

Memberships list your memberships in CloudRoute VPN groups and lets you create new groups. For more information on CloudRoute, please see 5.8, “CloudRoute VPN”

5.17. Pricing and payment

This section contains settings to track the price of :

  • Price calculation settings — used to track the price of objects shared by other systems. You can enter the Update interval to define how often your system should check for updates of the offered prices. By default, Asema IoT Central checks for updates every hour.

  • Payment acceptance — set the interface for paying for your objects. There options are:

    • on-screen popup in the app that prompts the user to swipe left to complete the payment.

    • NFC device.

5.18. Semantic data

The Asema IoT Central has an API which makes it possible for the system to send and request data in semantic format, namely many serialization formats of RDF. Supported serializations include Turtle, JSON-LD and N-triples.

When data is inserted or fed into the system, it is mapped between the local variables and a semantic vocabulary. If you create a custom schema which has its own data keys and would like to serve data from a device that uses such a schema in semantic format, the custom keys need a mapping to the semantic vocabulary.

In semantic data, a variable is bound to a verifiable URI that makes the definition globally unambiguous. The variable can be represented in full form with the prefix, e.g. http://www.example.com/definitions#temperature or by shortening the expression by defining the URIs as prefixes and then just expressing the variable with the prefix. For example @prefix myex http://www.example.com/definitions# and myex:temperature.

The prefixes can be automatically generated but for readability and ease of debugging purposes, the prefixes are defined explicitly. To do so, add a new prefix in Semantic data > Context URLs table by entering the prefix and the corresponding URL.

Once you have defined the prefix(es), enter the mapping into the mappings table. The vocabulary for measurable variables has been split into two: the name of the variable and the unit of the variable. For example if you'd measure speed, the variable could be velocity and its unit MetersPerSecond. Or if you measure temperature the variable could be SurfaceTemperature and the unit Celsius.

In semantic data both the variable and its unit must be defined unambiguously so you need to give a prefix for both.

5.19. Location

The location of your Asema IoT system is used in various features of the system, such as the location stamped on recorded database values and as a starting view of all the maps where you make edits.

The latitude and longitude (WGS-84) is used for this purpose. The postal address is an additional meta information that can be used for instance when managing several installations.

The latitude and longitude information can be entered as fixed values or you may set up the system so that it tracks values from a positioning device or an object in the system.

To set the geographic location of your Asema IoT, go to System > Location. You can use the following options:

  • Enter the system's postal address or fixed coordinates.

  • Read the system's coordinates from a source:

    A positioning sensor on this device.

    The position of some object that has a GPS device.

    A positioning plugin (available plugins are listed at the bottom of the page).

5.20. Maps

In the web admin interface, map views of Asema IoT use Google Maps as the map provider. But when you design mobile and desktop applications, Asema IoT provides integration to several map services that can be used as the map providers of that application. Asema IoT currently supports the following map services:

  • HERE

  • MapBox

  • ESRI

  • Open Street Maps

To choose the service to be used on Asema IoT Central graphical desktop, go to System > Maps.

Note that the commercial services offer a limited bandwidth access to their services for free. Asema IoT comes with a predefined key for this free access to most services. The capacity of these keys may be limited as the keys are shared.

For more capacity, you need to register your own account at the service provider. Follow the instructions offered by each provider on their website to obtain your access key (either free or purchased commercial). Then enter the credentials in the corresponding field.

5.21. Routing

By default, Asema IoT uses the routing provided by the map service you chose in System > Maps. You can also write a custom routing plugin. To upload it to Asema IoT, go to System > Routing.

Note

Routing here refers to finding a route on a geographical map for some vehicle such as a car. This setting has nothing to do with IP traffic routing.

5.22. Logging and console

To configure the logging feature of the system or view the latest log in a console, go to System > Logging and console.

In this section of the setup, you can perform the following actions:

  • Restart the application.

    Click the Reload button to restart the system. Restart will empty all caches, disconnect all connections and stop all timers and other logic. These are then reloaded into memory and connections are re-established. Users will remain logged in during this process but any network connections made by peer systems must be reconnected.

  • Set the developer mode on and off.

    If you are running the desktop interface, this option will enable and disable the developer controls from the screen.

  • Configure system logging.

    Here you can select the verbosity of the log from very brief to very verbose. By default the log output is shown on screen i.e. the terminal window from where the system has been started if a terminal has been used. Alternatively on systems that support a journal (systemd), the log may be redirected to it. As a final alternative, you can output the log into a file which will reside in the home directory of the application. The log is size limited and will be rotated once the limit is reached.

5.23. Startup

The Startup section provides the following startup settings:

  • Password and welcome screen requirement for the Asema IoT desktop application.

  • Fallback settings to use if there are some system configuration errors that make the application crush:

    Automatically load rules at startup — Untick it to start the application ignoring the standard rules (for example, if there is a loop in the rule)

    Instantiate QML of custom rules at startup — Untick it to start the application ignoring the custom rules.

    Activate hardware objects at startup — Untick it to prevent loading the hardware drivers.

    Block headless startup if peer connections fail — Untick it to quit startup in case some peers are offline.

5.24. About and license

About and license section lets you manage the Asema IoT Central license. You can view the kind of the license under which the system is running, as well as the number of objects and Asema IoT Edge applications connected.

To learn more about the license options, go to the Asema software licensing service page.

To validate your license and find out what licenses are available:

  1. Go to System > About and license and request a token.

  2. Go to the Asema software licensing service and enter the token there.

Chapter 6. Object connectivity

6.1. Introduction

In Asema IoT, objects represent all devices — either physical or virtual — and other data sources. Setting up and changing the objects is the core task in making IoT work with the system. The setup of each object defines precisely how the device or other system is connected to Asema IoT and how it behaves. Each object comprises:

  • Name. Quite simply the name of the particular object.

  • Identifiers. The identification of the object that allows applications and APIs find the object in an exact fashion. See below for details on identifiers.

  • Metadata. Object type-related or object-specific fields that describe what the object is like.

  • Schema. A schema is a technical definition of how an object type actually operates and interfaces with the world.

  • Connectivity settings. Object specific technical setup for its connectivity. The schema, i.e. the definition of an object class, and the settings, i.e. the definition of a particular object instance, together form the settings that make the object connect.

While the above defines the object, three types of continuously changing and recorded data are attached to the objects to record its actions and make it operate:

  • Properties. Properties are measurable and controllable attributes of an object, for example speed, pressure, temperature and similar freely defined variables that are written into a schema. As typical objects in an IoT system are some sort of physical objects, two multidimensional properties are available to all objects irrespective of their schema: their position (latitude, longitude and altitude) and orientation (yaw, pitch and tilt).

  • Events. These are things that have happened to the object, for instance if it has been broken and repaired.

  • Tasks. These are things that should be done to the object, for instance do a maintenance checkup.

Each object has the following identifiers that can be used in various applications for pointing exactly to that object:

  • Global Identifier (GID). Mandatory, fixed. A GID is the basic identification number every object has. When an object is created the first time, it is assigned a random identifier that is guaranteed to be unique across all systems. Once the GID is generated, you cannot change it. As the GID is mandatory, you can always find an object if you know its GID.

  • Object Identifier (Smart API identifier). Mandatory, editable. The Object Identifier is an extension to the GID used by the Smart API standard and the Asema IoT sharing functionality. Just like the GID, it is assigned to an object when the object is created. It comprises a domain part (http://[domain]) and an identifier part ([random string]) where the identifier part by default is the GID. The domain part makes using Object Identifiers easier in applications that stretch across organizations. Like the GID, the Object Identifier is unique for each object. However, unlike the GID, it can be edited and changed. The Object Identifier also makes it possible to track which objects are actually acting as copies of each other. When an object is shared and resides in two different systems, the copies of the object will have different GIDs but the same Object Identifiers.

  • Component Identifier. Optional, editable. The Component Identifier is an optional identifier to be used by applications to recognize an object meant for the same purpose although it may not be the same object. This identifier is used in situations where the same application runs on two different systems but with different data. For instance, there is an application for managing a baby monitor at a house. The same application can be run by different people in different houses and they all want to monitor their particular baby monitor. To avoid configuring the unique GID of the particular baby monitor to each application instance, the application developer can specify a Component Identifier, say "ourBabyMonitor" in the application and this is the only identifier that needs to be configured to the individual monitors. When you export and object and transfer it to another system via the import feature, the imported object will have a unique GID and a unique Object Identifier but the Component Identifier will be the same.

6.2. Object types

There are four broad types of objects in Asema IoT: Server API objects, Client API objects, Database objects and Hardware objects. As the core purpose of the system is to collect and unify data originating from various sources, all of these objects offer the same application capabilities and application API. Therefore, from an application perspective, it does not matter which object type is chosen.

However, from a connectivity point of view, the choice of object type makes all the difference as the purpose of different object types is to define how exactly the object acquires its data. So, in essence all object types serve their data the same way but acquire the data differently.

Note

All objects of any type are always available through both the JSON API and Smart API. If you intend to do system integration using either of these two APIs and do not require additional data source functionality for a particular object, it does not matter which object type you choose. Simply pick one that is easy to manage for you. In most cases the recommended choice is the Generic Object as it is easiest to configure and does not try to connect to any resource.

Depending on the type of connectivity, you should choose the object type using the following rules:

  • Generic object. Choose this type if you do not need any object connectivity but instead need a simple object for storing data and using that data in your application logic. A generic object has no interface, just API access.

  • Server API object. Choose this type when you want Asema IoT to act as a server that waits and receives the data. Typically in this case you are dealing with some other system that is able to push data into a given URL but you do not want or cannot change the format of the data that the system is pushing forward. A Server API object has a listener interface with a parser that can interpret the incoming data.

  • Network client object. Choose this type when you want Asema IoT to act as a client that actively fetches the data. Typically in this case you are dealing with a network server with a public API that responds to a data query. A Network client object has a requester interface that is designed to actively interact with an external server and parsers to interpret the data.

  • Database object. Choose this type if you have a database server with no network API and you'd like to fetch data from the database using SQL queries. A Database object has a database connection interface for directly talking to the database.

  • Hardware object. Choose this type if you have a hardware device which will interface directly with the unit where you installed Asema IoT. A Hardware object has a hardware driver interface that can interact with the hardware in case.

Each object type has its own connectivity settings. The chapters below describe these in detail. In addition to the connectivity settings, you need a schema. The schema defines what the data you manipulate actually looks like and how it can be turned into properties of the Asema IoT object. Schemas are shared across objects as most objects have similar data. So for instance, if a remote controlled crane sends data in a particular format and your IoT system manages one hundred cranes, there is no need to write one hundred schemas. Instead, you write one schema for a crane and assign that schema to all the cranes in the system.

Schemas control the so called parsers and serializers. A parser takes external data and parses it into the format needed by Asema IoT. A serializer does exactly the opposite: it takes data from Asema IoT and formats it into a format needed by some external system.

The format of the definitions of parsers and serializers will differ depending on the object type. As this is a broad topic, there is a separate manual on the exact details of schemas. Please refer to Object data parsing and serializing manual for details.

6.3. Creating an object

To create an object, you need to choose the object type, specify the connection parameters, select the object schema or a plugin to read the data and configure access rights.

These steps can be performed either with an object form in the Objects menu or with the object creation wizard available on the front page of the Objects setup (Create a new object button).

6.3.1. Using the object wizard

If you choose to use the object creation wizard, proceed as follows:

  1. Click Create a new object on the Objects page. Enter the object's name, description and the entity type (for example, a pump).

  2. Choose the data source, which corresponds to the type of object:

    • No external data source — For a generic object.

    • Some other system contacts my service to feed the data in (server) — For a server API object.

    • My system will listen to a data channel and topic for incoming data (subscriber) — For a hardware object.

    • My system contacts some other system for data (client) — For a network client object.

    • The data will be entered to a database for my system to read (database)— For a database object.

  3. Fill in the parameters for the chosen type of object (see the sections below).

  4. Define the access rights (see 6.5, “Managing object access rights”) and click Finish.

  5. Add a schema that describes how to parse the data. Schema is created for a particular object type, so choose the type of object you just created in the menu on the left and go to its schemas. For example, Server API objects > API schemas.

    Note

    This document doesn't provide information on how to write a schema. Please refer to the Asema IoT Central Object data parsing and serializing manual for details.

The object you created appears in the object list Control and Monitor menu. If you want to access the object settings, choose the object type in the Objects menu (see 6.3.2, “Using object forms”).

You can proceed to configuring object properties (see 6.4, “Configuring an object” ).

6.3.2. Using object forms

Object forms are used for creating objects or editing the object settings. The forms are type-specific: Generic objects, Server API objects, Network client objects, Database objects, Hardware objects. They can be accessed from the Objects menu.

The data of the object is split into read-only metadata and read-write properties. The fields of the metadata originate from various sources, including those mandated by a driver or object type. In addition, the object may have a metadata model which is a set of metadata fields for the object. If you need certain set of metadata about the objects, you can set up a metadata model in the Objects > Metadata models.

Each object also has a schema that defines what properties the object carries as well as much of the functionality. When you create an object with a form, you must link the object to a schema for the object to become valid (in the case of network client objects you actually need two schemas).

The content and syntax of schemas is a topic covered by the separate Asema IoT Central Object data parsing and serializing manual. This manual does not therefore describe the schemas in further detail.

In all object forms you may add the following identifying details (see above for their meaning):

  • Name

  • Description

  • Smart API object Identifier

  • Component Identifier

  • Metadata model

Additionally, you can write the object description. This is just a free-form text field that can contain any text you may find useful in remembering or communicating what this object is about.

The rest of the available fields depend on the object type.

6.3.2.1. Generic objects

Because the generic objects do not have an interface, they have a minimal number of object specific settings. The only custom setting is the schema chosen from the corresponding dropdown.

6.3.2.2. Server API objects

To set up a Server API object, you need to define:

  • Protocol. This is the network protocol used by an external client to feed data to this object. The following choices are available: HTTP(S), CaAP(S), MQTT and TCP.

  • Path identifier, topic or port. Depending on the protocol you've chosen, you need to specify some way to identify which access belongs to which Server API object
    • For HTTP and CoAP, it is a URL path. So if you enter here the value "path_to_my_object", this object (assuming localhost IP 127.0.0.1) can be addressed with http://127.0.0.1:8080/feed/path_to_my_object. Note the mandatory feedpath needed by the system to recognize access to the Feed API that serves these objects.
    • For MQTT, it is the topic. So if you enter here "iot/data/my_object", Asema IoT contacts the default MQTT broker and subscribes to the topic "iot/data/my_object". Messages received from that topic are sent to this object.

    • For TCP, it is the port number. So if you enter here 5555, Asema IoT will open this port for listening and data to TCP connection 127.0.0.1:5555 will be sent to this object.

  • Core type. This is the most basic classification of an object (you can make a much more detailed one with metadata). Simply says whether the object just reads values (a sensor) or can also control something (an actuator).

  • Schema. The schema used for defining properties as well as their parsing from the incoming stream of data.

6.3.2.3. Network client objects

Network client objects are used when Asema IoT acts as a client that actively fetches the data. Typically in this case you are dealing with a network server with a public API that responds to a data query.

To set up a Network client object, you need define:

  • Protocol. This is the network protocol used by the Asema IoT system to fetch to this object. The following choices are available: HTTP(S), CaAP, and TCP.

  • Target server address. This is the IP or domain address of the server to contact.

  • A path identifier or port. Depending on the protocol you've chosen, you need to specify some way to identify how in more detail to address the target server
    • For HTTP and CoAP, it is a URL path. So if you enter here the value "/json/my_object", this object (assuming server data.myiot.org) will be addressed with http://data.myiot.org/json/my_object.
    • For TCP, it is the port number. So if you enter here 5555, Asema IoT will try to contact a TCP port at data.myiot.org:5555.

  • Core type. This is the most basic classification of an object (you can make a much more detailed one with metadata). Simply says whether the object just reads values (a sensor) or can also control something (an actuator).

  • Active. Unticking this box disables the fetching timer and the object no longer tries to update its values.

  • Querying of values. This setting determines what triggers the fetching of values from the remote server
    • On request. The query is made whenever someone tries to read a value of a property of this object.

    • On timer. The values are queried regularly with a timer.

  • Schemas. As a network call involves two messages, a request and a response, a network client uses two schemas, one for each.

    Note

    If you are using a schema that defines Smart API as the standard data format, you may also include a value in the Smart API server identifier, which will identify the Smart API action used at the target server.

6.3.2.4. Database objects

To set up a Database object, you need to define:

  • Database identifier. This is the value in a database row or column that identifies the data of this particular object (it will be the value of a WHERE clause). The column itself is defined in the schema.

  • Core type. This is the most basic classification of an object (you can make a much more detailed one with metadata). Simply says whether the object just reads values (a sensor) or can also control something (an actuator).

  • Querying of values. This setting determines what triggers the fecthing of values from the database:
    • On request. The query is made whenever someone tries to read a value of a proprty of this object.

    • On timer. The values are queried regularly with a timer.

    • On trigger. The fetching is made when the database sends a trigger signal that data in the database has changed.

  • Schema. The schema used for defining properties as well as their parsing from the database table.

Important

Triggers work only if you use Postgreql as your database.

6.3.3. Scanning and adding hardware

Hardware objects are directly connected to the computer or device where Asema IoT is running. The setup process depends on the technology used for the connection. For wired protocols you need to type in the details by hand, whereas the wireless protocols support scanning.

6.3.3.1. Bluetooth

There are two major flavors of Bluetooth available: Bluetooth Classic and Bluetooth Smart (aka Bluetooth 4.0 and Bluetooth LE). Because Bluetooth devices emit a beacon signal, adding a Bluetooth device into Asema IoT is a matter of simple scanning. However, you must choose the correct Bluetooth standard to perform the scan in. Bluetooth Smart devices can operate either as connected devices or as simple data transmitters where the data is included in the beacon itself. These beacon only devices are usually so called Bluetooth tags. There are two major standards for the data in the tag beacon: Eddystone and iBeacon. If you are using tags, please also choose the correct beacon format when initiating the scan.

Note

There are several ways a Bluetooth device can communicate with its counterparty. These are defined as Bluetooth profiles. For Bluetooth Classic, Asema IoT always uses the RF Comm profile, making it a device that sends and receives serial data. The schema for Bluetooth then defines how this serial data is interpreted.

To be able to use hardware over Bluetooth, you need to have a computer with Bluetooth radio and must tell the system which Bluetooth adapter you want to use. To do so, enter your Bluetooth adapter MAC address in Settings > Bluetooth. Note that if you want to use a particular Bluetooth standard (Classic or Smart), your Bluetooth hardware must be compatible with that particular standard. Most modern Bluetooth chips support both but not all of them.

To do the scan, go to Objects > Bluetooth and click Add new. Choose the appropriate scan and start it. Once a beacon from your hardware device is detected, the device is shown in the scan results. Click Save to finish the process.

Important

On Linux systems the beacon scanning is done by a background daemon called proximity_listener. To be able to do the scan, please ensure this daemon is running.

6.3.3.2. NFC

NFC (Near Field Communication) is a very short range radio standard found today commonly in payment cards, travel cards key fobs, and smart phones. While NFC itself is a standard radio format, there are several substandards to it, each suitable for a particular application such as credit card payments. Asema IoT does not support these substandards but does recognize all NFC cards and can extract the basic information of the cards such as the card number.

To use NFC, you need to have a device with NFC capability. On smartphones and tablets an NFC chip and antenna is typically embedded in the casing of the device. On PC's you will typically need a USB connected card reader.

To connect a device with NFC, go to Hardware objects > NFC and click Add new. Activate the cardreader by clicking Start scan. The scanned device becomes an object in Asema IoT system.

Important

On Linux systems the NFC scanning is done by a background daemon called proximity_listener. To be able to do the scan, please ensure this daemon is running.

6.3.3.3. Modbus

Modbus is a serial standard commonly found in industrial devices. Modbus can be used either with a direct serial connection (RTU) or over an IP network (TCP). In either case, you need to manually configure the connection parameters and write a schema that fits the bit/byte order of the Modbus-compatible device you are using.

If you use TCP, type in the IP or domain address of the Modbus device, together with the port.

If you use RTU, enter the serial communication parameters (Baud rate, Data bits, Parity, Stop bits, and Flow control) that match those used by the serial connection of your Modbus device. Also, enter the correct serial port to use into the Address field.

Note

For details on the Modbus schema and how to write one, refer to the Asema IoT Central Object data parsing and serializing manual. As an alternative to a schema, you can write a completely custom parser plugin that does the conversion.

6.3.3.4. Serial

Serial devices simply transmit raw bytes over a wire and interpret the bytes as property values. The interpretation is done by a parsed with the help of a schema that customizes the parser. To use a serial device, connect it to a serial port and type the name of the serial port into the Address field of the configuration form. Then enter the serial communication parameters (Baud rate, Data bits, Parity, Stop bits, and Flow control) and make sure they match those used your serial device

Note

For details on the serial schema and how to write one, read the Asema IoT Central Parser and serializer manual. As an alternative to a schema, you can also write a completely custom parser plugin that does the conversion.

6.3.3.5. Custom hardware drivers

If you have a hardware device that does not conform to any of the models readily available in Asema IoT, you can program a driver for it as a plugin that is completely custom. The plugin is a C/C++ program compiled as a dynamically linkable library (a .dll or .so) which you Asema IoT loads at startup and connects into the object framework.

This manual doesn't provide information on how to write those plugins. For details on plugin programming, including custom hardware driver plugins, refer to the Asema IoT Central Plugin programming manual.

Once you programmed a plugin, add it to the system by placing it into the plugins directory of your installation (see the Asema IoT Central Plugin programming manual for details). Then restart the system, go to Hardware objects > Custom and click Add new. If the plugin is programmed correctly, you can choose the driver from the dropdown menu here.

6.4. Configuring an object

Once you created an object, you can further configure its behavior by editing object metadata, configuring how it writes measurement values into the database, and whether and how notifications of changes into properties are sent forward.

6.4.1. Object metadata

If there is any object metadata that should be used by the Asema IoT Central or by the device driver, specify it on the Objects > Configure page. Click the gear icon in the Metadata column and fill in the fields:

  • Common metadata — Includes the the object location.

  • Custom metadata — Any kind of information about the object that you need to specify. For example, the device model. To enter it, add a text field "Device model" and then enter the model name as a value.

  • Extended metadata — Information used by the hardware object's driver (if you programmed one).

  • Default property values — Values used by the plugin (if you programmed one).

6.4.1.1. Setting up the metadata model

If you have multiple objects of the same kind (let's say, cars for rent), you might need a custom form to to store the necessary information about each of them. To do it, create a custom form with the necessary fields (such as, for example, the manufacturer, production year, number of seats and so on), link it to the object and enter the details in it.

  1. Go to Objects > Metadata models and click Add new.

  2. Enter the name for the metadata model.

  3. Create the metadata fields: choose the field type and label.

  4. Save the data model.

Now you can link the form to the objects you create.

Once you entered the meta data when creating the object, you can edit in in Objects > Configure > Metadata > Custom metadata.

6.4.2. Database logging

Asema IoT can record the values received from the object to the database.

To set up database logging for an object, go to Objects > Configure and click the gear icon in the Database logging column. Choose the logging options and click Save.

6.4.3. Notifications sending

To send the object's data to the MQTT broker server, specify the server and the topic in the object's settings.

To do this, go to Objects > Configure and click the gear icon in the Notifier column. Choose a notification broker in the Server field (the server must be present in System > Notification sender). Specify the message format and the three parts of the topic name (Publisher type, Conversation ID, Conversation type).

6.4.4. Subscriber settings

If you are using Asema E gateways, those gateways will send notifications of property values only when the values of the properties change. In case no change is detected, the Asema IoT will not receive any values until change. To get regular updates of property values even when values remain static, you need to inform the gateway to do so.

To subscribe to the property on a regular basis, add it to the subscriber settings. The setting is simple, it is just a list of property names, each with its own entry. These properties will get regular updates, others only change notifications.

Note

Subscriber settings are only available for objects that originate from Asema E compatible gateways. On other objects they have no effect.

6.5. Managing object access rights

Depending on the interface the user is working with, you can control the user's access to the objects with the following tools:

  • Zone- and user group-based access in graphical interface.

  • API key for JSON API.

  • Offers in Smart API.

  • Sharing objects with peers via Smart API.

6.5.1. Zone- and user group-based access

In graphical interface, the access to object is based on zones and user groups. An object is assigned a zone that limits the access to the specified geographical area and (optionally) the time period. Then, you can set which usergroups have access to the zone.

Thus, object O linked to zone Z can be accessed by the user groups that have access rights for the zone Z.

To configure the object access:

  1. Create a zone and configure the zone access rights.

    Go to Objects > Zones and click Add new. Fill in the fields:

    • Name of the zone.

    • Access rights for each user group:

      View — View the object's properties and settings.

      Edit — Edit the object's properties and settings.

      Delete — Delete an object.

      Control — Set the object's property values.

      Record — Record the object's property values.

      Set target — Set target for an object's property.

      Bid — Create offers for buying the object's properties.

      Ask — Create offers for selling the object's properties.

    • Limit to area — geographical area. To add a map area from the Content menu, choose it in the Copy from area list.

    • Valid from, Valid until — The period in which the specified user groups can access the zone's objects.

    • Description of the zone.

  2. Assign the zone to the object.

    Go to Objects > Configure and click the gear button in the Access control field next to the object. Tick the Enable zone based access control for this object option, choose the zone and click Save.

  3. Turn on zone-based access to the object.

    Go to Objects > Configure and put the Access control switcher next to the object to ON.

6.5.2. Access via JSON API

You can define if the object is available via the JSON API.

To do this, go to Objects > Configure and click the gear button in the Access control field next to the object. Set the access level in the External access with generic API keys section and enter the API keys.

6.5.3. Access via Smart API

Via Smart API, access to objects can be bought when the user receives an offer. To enable the offering protocol for an object, go to Objects > Configure, click the gear button in the Access control field next to the object and choose Offering protocol enabled in the External access through Smart API section.

6.5.4. Sharing settings

To publish an object for sharing to other systems, you need to open peer access to it. Choose one of the options:

  • Sharing disabled. Not visible in Smart API Find searches.

  • Sharing enabled. Always visible in Smart API Find searches.

  • Sharing enabled. Visible in Smart API Find searches only when an offer is in force.

For more information about sharing functionality and settings, see 8, Sharing.

6.6. Using the control dashboard and graphing values

To track the object data and control the object, go to Objects > Control and Monitor.

Here you can:

  • Get information about the object.

    The information about the objects is displayed in the table on the Objects page. You can see the object source (if the object is local, pooled or shared) and connection status (online or offline).

    To view the object identifiers, click the information icon next to the object.

  • Check if the object is online.

    To do this, click Ping. If the object is connected, it shows a heartbeat sign. If it is disconnected, an error is displayed.

  • Create events and tasks related to the object. To do this, click the gear icon in the Events or Tasks column and fill in the fields. Events and tasks are displayed on the Object events timeline.

  • Generate reports in XLS and PDF format (see 13, Generating reports).

  • Set up a dashboard for monitoring and controlling the object.

    To create a dashboard, click the gauge icon next to the object to go to the dashboard page. Then click the button in the upper right corner of the page to add elements and controls, such as gauges, charts, property setters and sliders, maps and so on.

    To save the dashboard, click the save icon at the top of the page.

6.7. Importing and exporting objects

You can import and export objects between different Asema IoT instances. Object information is saved in the JSON format and can be downloaded in a text file. To export or import an object, go to Objects > Import/Export.

6.8. Deploying objects with Asema IoT Central mobile app

Asema IoT allows you to add remote objects to your system using the Asema IoT mobile app. It is especially convenient if you need to connect multiple remote devices located in the field. Imagine you have a company maintaining windmills and you need to monitor hundreds of windmills in various locations. You want to add them to the system, and for each windmill, you want to have coordinates. manufacturer and the product ID. All of these can be obtained only on the spot. To do it, you would need to do the following:

  1. Feed the list of objects in Asema IoT. You can do it through the API or on the Objects > Import, export, deploy > Import placeholders from file page.

  2. Add the object schema and specification in JSON on the Objects > Import, export, deploy > Manage undeployed page.

  3. Create a metadata model and link it to the deployment form on the Objects > Import, export, deploy > Manage undeployed page.

  4. Add the deployment instruction on the Objects > Import, export, deploy > Manage undeployed page. This instruction will be shown in Asema IoT Dashboard app.

  5. Print out the QR codes for the objects (optionally, if you want to avoid searching for the object in the list).

  6. On the spot where the object is located, stick the QR code to the object and then scan it with Asema IoT Dashboard app. The app will show the instruction and prompt you to fill in the meta data fields. After deployment is completed, the object will appear in Asema IoT.

6.9. Managing connected hardware

The list of connected hardware is available on the Objects > Hardware objects > Manage page.

To delete a connected device, click the trash icon.

To reload all drivers, click Reconnect.

Chapter 7. Connecting several IoT systems together

7.1. A comparison of available connection methods

Asema IoT Central supports four methods for connecting objects between systems such as two separate IoT clouds or an IoT server and some webservice. Two of the methods require manual configuration and two are automatic and self-configuring:

  • Manual configuration with object schemas.

    Create either Server API objects or Network client objects and define in their schemas how they receive or fetch information from remote systems. See 6, Object connectivity for further details.

  • Programmatic access using the JSON API or the Smart API.

    Create scripts and programs that modify the properties of the objects through the programming APIs of Asema IoT Central. Please read the Asema IoT Central JSON API manual or the Smart API Programmer manual, respectively, for details.

  • Pooling.

    Pooling is a remote object mirroring method available between two systems that run some version of Asema IoT (Central, Edge, Dashboard). Two pools connected together mirror their objects and their property states. The properties are mirrored as such, no configuration in between is possible. Pooling is possible between systems that belong to the same group. Data exchange is assumed to be open within the group. Transactions (such as payment) for data sharing are not recorded.

  • Sharing.

    Sharing is an automated connection method that uses Smart API definitions for mirroring data. It is available between any system that is Smart API compatible. Objects can be modified in their schemas to automatically convert to some local property convention. Logging of transactions between shared objects is possible, making payment tracking also available for this method.

Each of the listed methods has its strengths and weaknesses depending on the integration scenario. As a rule of thumb, the following recommendations can be used:

Use manually defined schemas when:

  • You are connecting to a remote system that uses some proprietary API format with no standard.

  • You can't modify the counterparty and do not want to add converters or other systems in between.

Use API programming when:

  • You have the skills to program JSON network queries or the Smart API SDK and can add such a program as an adapter between systems.

  • You want fully custom logic into the integration and how data is processed.

Use pooling when:

  1. You have two instances of Asema IoT and simply want to sync everything without any further hassle.

  2. You want simple global configuration for all objects without further tracking and payment processing.

Use sharing when:

  1. You want to use advanced features such as automatic unit conversion, end-to-end encryption and payments.

  2. You want to publish items and data into a directory for others to find.

  3. You want to connect an Asema IoT instance with some Smart API compatible system that is not Asema IoT.

As the programmatic methods are discussed in detail in this manual and separate programming and configuration manuals, this chapter focuses on explaining the two automatic methods, pooling and sharing and their capabilities and differences.

7.2. Sharing versus pooling: key differences

7.2.1. Use case example

Sharing and pooling are two automatic methods used when combining Asema IoT objects of two (or more) systems together. While both aim at the same goal, the methods have some key differences. In short, pooling is a straightforward and fast "share all at zero cost" approach while sharing is a more granular method that allows finer control and cost accounting.

To illustrate the two, let's take a case example. In this use case we'll have two neighbouring farms, let's call them "Farm West" and "Farm East". Both of them have harvesters to collect the crop and trucks to carry the produce to the market. Farm West owns three harvesters and one truck while Farm East has two harvesters and two trucks.

Now, because the machines are highly sophisticated and crucial to the operation, both farms want to take good care of the equipment. A local company "MainCo" offers maintenance support for them. MainCo remotely monitors the equipment and in case of problems, such as excessive heating or leaks, they take action. Both farms are monitoring their equipment with Asema IoT, so the easiest way for MainCo is to take into use an instance of the same system and gain access to the data of both farms.

In the Asema IoT Centrals the farms run, the equipment is represented as objects in pools. A pool is simply a collection of all the items in the system. So, Pool West comprises three harvesters and two trucks and Pool East has two harvesters and two trucks. If MainCo now wants to access this data, it can either use pooling or sharing. This results in a third pool, Pool MainCo, which is a combination of the other pools.

If MainCo uses pooling, Pool MainCo will simply get a mirrored copy of the objects in the other two pools. So as a result, Pool MainCo will now contain five harvesters and three trucks. MainCo sees them in one unified view and can monitor both farms with ease. It can even establish applications for different purposes. The harvester maintenance application would see five harvesters. The truck maintenance application would have access to three trucks.

Pooling is easy to conceptualize and fast to establish technically. Simply combine the pools and voilá, you have a union of two pools. However, the simplicity comes with a downside as real-life situations are often complex and require some more granularity. For instance, if pooling is used, MainCo always sees all equipment and because there is no accounting involved, most likely the pricing they employ will be simple: a monthly monitoring fee plus some fee for each repair once that occurs.

If something else is needed, this is where sharing comes along. Let's assume that one of the harvesters at Farm West is an older model that has been maintained by the farm owners for years. They already know all the quirks of that individual and are reluctant to outsource the maintenance. Farm East on the other hand is fine with outsourcing all machines but thinks most of the equipment is so new that constant monitoring is not worth the price. They'd like to outsource maintenance but pay only when problems are detected.

Sharing makes both those scenarios possible. Pools are combined on a per object basis, meaning that one object is easy to exclude. Advanced pricing scheme allows Farm East to apply a specific price list based on sent alarms only. For MainCo's operation, the system is still as fluent as ever. They now see four harvesters and three trucks in their system which automatically keeps track of all the actions they perform and does the accounting needed for custom billing.

7.2.2. Feature comparison

The technical differences between sharing and pooling are listed below:

AspectPoolingSharing
What is sharedAll objects in the remote pools are copied. Only objects that are shared are copied.
Object availability if connection is lostThe combined pool is a virtual representation of the remote system. The copied pool has no permanent local representation. If the connection to the peer system is lost, the copy is also disconnected and disappears. No shadowing is available.The combined pool is a mirrored copy of the remote system. The copied objects have a permanently stored local representation. If the connection to the peer system is lost, the copy remains in the system. Shadowing can be used to cache the commands given during offline operation and sync these when a connection is re-established.
Access limitationsZone limitations per remote userIn addition to zones, access may be limited by time, place, paid amount and other factors.
Payment and accountingAccess to all objects is assumed to be free. No accounting is made on the number of controls or amount of data shared. An accounting system keeps track of the changes made and amount of data shared, making it possible to also charge money for them.
Object IDThe mirrored copy will have the same Global Identifier (GID) as the original.The mirrored copy will have a different GID than the original. However, their Object Identifiers (also known as the Smart API identifiers), will be the same.
AutomationNo cost-saving automation is possible because it is assumed there is no cost.An optimization routine can be assigned to the object to automate when and how various properties are set.
Connection to peerThe systems that share data must know each other in advance so that they can configure each other as pooling peers. Data about objects can be stored in the Smart API Find directory from which various parties can search for objects that would fit their needs and send connection requests.
Data securityData is always protected by the network layer using HTTPS. If no HTTPS connection is available, data transmission will be in plain text.Each message can be encrypted end-to-end, keeping the details secret even when there is no network level encryption.
Data outputData is transmitted "as is". The communicating parties need to understand the units and the classification without further meta information about it. Data is in semantic format and includes, for instance, information about the units, making it possible to do unit and currency conversion on the fly.
Network protocols usedAll data sharing is assumed to happen over HTTP (possibly through a VPN). Multiple protocols including HTTP, MQTT and CoAP can be used simultaneously depending on the object and communicating party.
Software requirementsAll systems that share pools must use Asema IoT software and the pooling protocol. Any system that has integrated the Smart API SDK can participate in sharing.

7.3. Setting up pooling

Pooling is set up by configuring the pooling peers in System settings. Once peers have been entered, they will automatically establish the pooling connection.

For details on the setup, please read 5.7, “Peers and gateways”.

7.4. Setting up sharing

Sharing setup involves opening access to individual objects in the system and announcing them to the Smart API Find directory which a connecting system uses to subscribe to them.

This procedure is explained in detail in the next chapter 8, Sharing.

Chapter 8. Sharing

8.1. Introduction and key concepts

Sharing is the process of opening an API for an object to some remote system. Opening means:

  • Issuing access credentials to some other party for accessing the system

  • Publishing the details of the technical interface specification to the other party for making a connection that accesses the object

In sharing, the system that "owns" the object and shared it (the "publisher") exchanges messages with the counterparty that subscribed to it (the "subscriber") using the Smart API semantic protocol. Each data exchange is authenticated and — if so desired — signed and encrypted. The data exchange may also contain an offer. Including an offer in a message means that the publisher requires a payment or some other form of contract before the requested data or control can be accessed. The subscriber must accept the offer and repeat the request for it to pass. Accepting an offer in essence creates a contract for a micropayment per each exchange. A notary protocol can further be used to enforce the validity of each such exchange.

8.1.1. Data requests and notifications

Data exchange between the publisher and the subscriber may take place in two primary modes:

  • A request initiated by the subscriber

  • A notification sent by the publisher.

Usually fetching data or commanding a change in value takes place as a request. But when a property value actually changes, this update in the data is shared with a notification.

An exchange that results in the change of a value therefore usually involves a combination of the two methods: the first stage is a request by the subscriber to change a value. The publisher confirms this back as a response to the request, confirming the value it intends to set the property to. However, as the actual change may take time, the confirmation of the actual effective change is done asynchronously. Once the property has changed, the publisher sends a notification and this finally confirms the action.

There are several methods and protocols available for both the requests and notifications. Depending on the network configuration you have, some may be suitable some may not (e.g. due to firewall configuration). This is why Asema IoT offers multiple options for both. When the publisher announces the sharing of an object, it will in the announcement include which method(s) it supports for both requests and notifications. The subscriber then chooses the most appropriate method from the presented choices while accepting the subscription.

8.1.2. The offering protocol

Whenever a subscriber initiates a request to the publisher for an object that needs to be paid for, the initial response to the request contains an offer. For the communication to proceed and the request to actually pass through, the subscriber needs to accept that offer by signing it.

The offer specifies the price for accessing the object and the object's availability. For example, an offer may be equivalent to this: "This parking slot is available from 8 a.m. to 5 p.m. at a price of 4 euro per hour". Note that because the offering may be attached to any response to some request, the publisher may vary the price in the offering over time or per counterparty. For example, in the case of parking the parking may be cheaper on pubic holidays or priced differently for permanent residents.

If the subscriber wants to accept the offer, it will electronically sign it. This signed offer is sent back to the publisher to form a contract. After receiving the signed offer, the publisher confirms the signature and responds with the actual requested data or performs the requested modification to a property.

8.1.3. Authentication, authorization, signing and encryption

Asema IoT Central secures object access during sharing with authentication and authorization methods that only allow access to the objects to authorized parties. To control how strict this access is, you can configure the access control per each object in object configuration (see 6.5, “Managing object access rights”).

At the core of access control are credentials to a system, usually a username and a password. On the publisher side, these are stored as a user (and set up in the Users section of the web admin interface). On the subscriber side, the credentials are set up in the System settings under Credentials.

As sharing is a process that runs between two automated systems, in most cases human intervention is not intended nor desired. Therefore security mechanisms must also run automatically. Sometimes, especially within closed corporate environments, academia or labs, such protection is not needed. Asema IoT Central therefore also allows for easing the security requirements. In the most lenient configuration credentials are created on the fly when the sharing process happens. Do however note that this approach is most vulnerable to hacking as the credentials would be given to anyone who is asking for them.

Note

If you are using the Smart API SDK to integrate some third party system with Asema IoT Central, note that this system must have its own access control methods in place. In general, systems that use the Smart API sharing protocol should enforce their security policy in the manner considered suitable for them in that system. It is important to note that while the Smart API protocol offers the tools to do so (e.g. signing and token generation), it does notdo the actual blocking of access. Asema IoT Central has its own security module to perform this task.

Depending on the strictness of the security policy, the parties have a choice on how to agree on the credentials.

  • The credentials are determined between parties out-of-band. If the publisher runs Asema IoT, the credentials are set in the System> Credentialssetup and attached to a group which has control over a set of objects. The username and password is sent to the subscriber with some secure, unrelated method (encrypted email for instance). On subscriber side, the credentials are added manually into settings.
  • The credentials are stored with a trusted third party e.g. an OAuth server. The security policy, enforced by a group that links those credentials to objects is created manually by the system admins.

  • The credentials are stored with a trusted third party e.g. an OAuth server and the policy that grants access is also at a trusted third party. The group that links those credentials to objects is created automatically when a policy extension message is sent by the policy server.

  • The credentials and the policy are created as an automated process when the subscription is made.

In addition to authorization, Asema IoT Central supports confidentiality of messages, signing to ensure message integrity and non-repudiation of signed contracts.

For this purpose, each party has a public key/ private key pair. The pair is generated and maintained in System setup under Smart API.

Important

You will need the keypair (as well as a unique Smart API ID) for sharing to work, this is why the sharing features are disabled until you generate those.

8.2. Subscribing to an object

To be able to access an object shared (published) by another party, you need to subscribe to it. In a subscription, your system first finds the object to subscribe to and then connects to the interface listed in the object's details. The search is done and details are received from the Smart API Find directory which holds information about all objects offered for sharing. Once connection is established, your system authenticates itself and asks for a subscription. If accepted, your system receives all necessary data needed to further access the object, to request data and notifications from it, and to control it.

Instructions on how to perform the search and the subscription are given below. Note that in order to get access to the system that published an object for sharing, you most likely need (the other system may have relaxed these requirements):

  • Username and password to the other system.

  • Account in that system.

If you don't have the credentials, you will need to ask for them from the administrator of the other system. Then add the credentials to System > Credentials > Client passwords for accessing remote systems. To help in the process, the system may at its choice support a common credential from the OAuth server.

If you don't have an account, you can request that also from the other system. This can be done with whatever method the administrator of the target system accepts and finds suitable. To help in the process, you may send an account request directly from the Sharing interface, see below for details.

8.2.1. Searching for shared objects to subscribe to

To find an object you want to subscribe to, go to Sharing > Subscribe/Buy and click Find more. Then optinally choose the filters that limit the search results. Click Find to display the items available in the global Smart API Find registry.

At each search result, click on the plus icon to add it to the list of candidates. You may then continue searching and adding the results into your list of candidates. Once done, close the search dialog.

If you didn't find an object that suits your needs, you might want to create an open offer for obtaining one. In Sharing > Subscribe/Buy, click Create a new offer, enter the title and describe what you are searching for. Sellers will be able to view it in the sellers' market available at Smart API Find service.

8.2.2. Activating the object to subscribe to

Once you have the list of objects to subscribe to, continue with the subscription process with each item. Click the Subscribe button next to the item. This opens a dialog that allows you to configure the connection. Here, select the credentials needed to access the target and sharing method to use.

First, select the credentials to use for authentication. Note that this selection must match the username and password in the system you are subscribing from (target).

Next, select the protocol to use for data transfer, and once done, click Subscribe.

If an account exists at target system and the credentials match, the object will be subscribed to.

Note

If you do not have an account at the system you are subscribing from, you can conveniently request one by clicking on the account request icon. Note though that you cannot continue the subscription until the account request has been accepted by the administrator of the target system and the account has been created.

8.2.3. Editing the schema for the obtained object

Once you made a subscription, you may use the object as such or modify it. Sharing lets you not only receive the object's data, but also redefine and extend the object's schema to better fit the data for your needs. This is done by editing the schema.

Important

If you edit the schema do not change the identifiers of the properties. These identifiers are used to match the properties of the target system with your system. If you change the identifiers, the systems will no longer be able to sync the commands properly.

A common use case for modifying a schema is unit conversion. For instance, if the object is used in two organizations that use different measurement units or currencies, this conversion can be made automatically and on the fly. If Asema IoT receives data with a different unit than the one specified in the schema, it will automatically try to convert between these two units. You can also set minimum and maximum levels for values that are only enfored locally in your system. Further, you can extend the schema to include additional property values that are not in the original shared object. In this case, the remote system will provide values for some properties while the local system supplies the others.

To edit the schema of an object you obtained, go to Sharing > Monitor and manage and click Edit schema next to the object in the Current obtained remote objects list.

Once the schema is edited and saved, it is reloaded and applied automatically in the data exchange.

8.3. Publishing objects for sharing

In addition to subscribing to objects of some other system, you can publish your objects for others to subscribe to. To publish an object, you need to:

  1. Allow sharing of the object.

    When an object is published and then subscribed to, the subscriber is given access to that object. As this is a security exception, in order to publish objects, you need to accept such exceptions per object. This is done by enabling sharing for that object in the access control settings of the object. You will not be able to share an object before you configure the access control of the object to allow this.

    Depending on the type of access control you define, the object you share will appear in the Smart API Find directory either automatically or after you have added an offer to it. The data in the directory will contain all necessary information for other parties to find the object and to technically contact your system and automatically configure the connection.

    For instructions, see 8.3.1, “Enabling sharing of an object”.

  2. Optionally, create an offer.

    This will add pricing details of the object and require subscribers to accept that offer when they access the object in your system.

    For instructions, see 8.3.2, “Making an offer”.

  3. Optionally, create accounts for buyers to hold a bookkeeping of the transactions and the purchasing power the user has when accessing the object.

    When offers are accepted and the acceptance involves a payment, that creates a transaction. The transactions are tracked with an account. In order for the sharing to work this way, each subscriber needs an account which is the final required setup that needs to be done.

    For instructions, see 8.3.3, “Creating buyer's accounts”.

Note

The way your system then handles the incoming requests targeting shared objects will depend on the trading conditions you set up. The default values at installation are reasonable for most usage scenarios but you may want to change and pay attention to these especially when running a commercial operation. For details, see 8.6.2, “Adjusting access control for shared objects”

8.3.1. Enabling sharing of an object

To enable sharing of an object, you need to modify its access rights. Go to Objects > Configure and click the gear icon in the Access control. In the window that appears, choose Sharing enabled.

The object will appear on the list on the Sharing > Publish/Sell page. Now you can offer it to other users.

Important

Whether the object appears in Smart API Find central directory for searches will depend on the type of sharing you allow in access control. You may choose to publish the object always or only after an offer has been created. In the latter case you naturally need to create the offer before anyone else can search for the object in the directory.

8.3.2. Making an offer

To create an offer:

  1. Go to Sharing > Publish/Sell. The table Local resources available for sharing table lists all the objects where sharing is enabled in their access control. Click Make an offer. Next, set the conditions for your offer:

    • Time of day when available, Dates when available — Time conditions for the offer.

    • Available at this distance from me, Available at a given country, city or address — The area for which the offer is valid.

    • Available only for listed users — The users who can receive the offer.

    • Available when these rules are in force — Custom conditions set through rule automation functionality. For example, to make an offer available only when the temperature outside is less then 0, you can set a rule "If the temperature outside is less then 0, this rule is true". Then, choose the Available when these rules are in force condition for the offer and select the rule.

  2. Set the pricing type:

    • Free of charge.

    • Fixed price for a period (hourly, daily, monthly etc fee).

    • Price per transaction (per control, read, write, etc).

    • External pricing source (you need to write a plugin for fetching the data).

Once you accept to publish the offer, it will be posted to Smart API Find. It is also be displayed in the list of open offers (Sharing > Publish/Sell) from where you can cancel it if necessary.

8.3.3. Creating buyer's accounts

If there's a buyer interested in your offers, you will receive an account request in Asema IoT Central. To sell an object to the buyer, you should accept the account request and (if needed) set limitations on how the buyer's account can be used. For example, should there be credit limit, if the positive balance is required, and so on.

To view and accept the account requests from buyers, go to Sharing > Accounts.

To create limitations for the buyer's account, click the gear button in the Sales accounts list. Fill in the fields:

  • Counterparty ID — The ID of the Asema IoT Central to which the objects are shared.

  • Users — Users of Asema IoT Central to which the objects are shared..

  • Valid from/until — The period for which the account can be used to purchase your objects.

  • Required initial balance — The balance needed to open an account.

  • Minimum balance — The minimum amount that must be left on account after a payment. If there's less funds on the account, the account is frozen.

  • Maximum balance — The maximum amount the account can hold.

  • Credit limit — The maximum amount the balance can be on negative ("on credit").

  • Prepayment limit — The maximum amount that can be prepaid.

  • Relaxed limits — Whether it is possible to exceed credit limit and go under the minimum balance.

8.4. Managing sharing

Once you have either subscribed to (purchased) or published (sold) objects, the Sharing > Monitor and manage section has the tools needed to manage those objects and monitor their state.

If you are a subscriber, you can:

  • Monitor how much money has been spent in using this object (if applicable)

  • Display information on the object and its identifiers. Additionally you can assign a Component Identifier for a shared object so that it can easily be used in Screenlets and Web applications.

  • Create automation routines that will try to optimize the usage pattern for the object.

    For details, see 8.4.2, “Creating and using optimizers”.

  • Edit the schema of the shared object.

    For details, see 8.4.1, “Editing schemas”.

  • Cancel the subscription and remove the object from your system.

If you are a publisher, you can:

  • Monitor how much money has been earned from other systems that are using this object.

  • Cancel the publishing and block shared access to the object.

8.4.1. Editing schemas

The primary purpose of editing the shared object's schema is changing the units used in the property values. This will allow you to automatically make conversions in unit values when data is exchanged between organizations.

To edit the schema, click the "Edit" icon in the list of obtained shared objects. In the form that opens, you will find the shared object's schemas. There are two sides to the connection: the request side (what is sent to the publisher) and response side (what is received from the publisher).

To set the unit in which the data is sent to the publisher, edit the request side. In case your system handles the values in a different unit, a conversion is made prior to sending (note that the publisher is capable of doing the conversion, too).

To set the unit in which your system is using the data (i.e. the unit to which the value is converted to), edit the response side.

8.4.2. Creating and using optimizers

If you click the "Automate" icon in the list of obtained shared objects, you can set an automatic optimization routine for the object. For more details on how to do this, please refer to 16.2, “Optimization”.

8.5. Shared object characteristics

A shared object has features you can use to change the objects and their behavior when necessary. The main characteristics are:

  • The Object Identifier (Smart API identifier). This identifies the object uniquely and globally in the format required by the Smart API standard.

    You can edit this identifier in the setup form of each object. However, if you do not enter an identifier manually, it will be formed automatically by the system by combining the domain of the system with the GID of the object.

  • One or more interfaces that let other parties contact this object over the network.

    In Asema IoT Central, the interface is determined automatically.

  • Availability conditions.

    When an offer is made, it can contain restrictions on when the object is accessible. These are called availability conditions. If availability conditions are not set, it is assumed that the object is available always without further limits (such as time of day).

  • Access control methods that limit access to the object to authorized parties.

    If an access control method is missing, it is assumed that the object is open for access by anyone.

  • A set of properties that external systems may manipulate. On Asema IoT Central, these properties are taken from the object schema.

8.5.1. Semantic object properties

When an object is manipulated with a protocol that uses Smart API — such as the sharing protocol — an object may have its properties specified with the semantic vocabulary of Smart API. This approach creates a very comprehensive set of definitions for a value that brings several benefits:

  • Semantics supports a universal and uniform definition of quantities and units. With the vocabulary for quantities and units, two systems can communicate the values of various variables and convert these values to the units they want on the fly. An airplane maintenance company could, for instance, track plane ground speed in miles per hour, while the planes send those values in kilometers per hour.

  • Semantics defines classification hierarchies that can be used to generalize the data. An airplane ground speed and airplane airspeed are different measures but they are both measures of speed.

  • As semantic data is linked data, also property values may be linked and can be defined in linked format and can include a measure of confidence interval. For instance airplane ground speed can be measured with a GPS with some accuracy or it can be calculated as a function of (i.e. be linked to) airspeed, wind speed and wind direction.

Schemas in Asema IoT Central currently support five variables that can be attached to a property to describe it: the predicate, the identifier, the quantity, the unit, and, of course, the value.

Variable

Description

If the property is mandatory

Predicate

Determines the relationship between the host object and the property. For example, if the object is a box and its color is blue then the relationship between the box and blue is the predicate "color".

Yes

Value

Plain and simple, this is the value. "Blue", "1001.0", "horse" or whatever the value of something may be.

Yes

Identifier

Identifies a particular value. Usually used with groups of values to identify a certain value. So, for instance, if a box has a predicate "color options" which has taken values "blue", "red", "yellow", an identifier can be used to point to for instance the default color.

Mandatory items in groups of values.
Quantity

Defines what is measured (as opposed to unit that says how it is measured). If a box has a certain volume, then the quantity would be "volume".

No
Unit

Defines how something is measured (as opposed to quantity that says what is measured). If the volume of the box is given in litres, then the unit would be "litre".

No

For sharing purposes, quantity and unit are two important variables to define as they greatly help the parties to interpret the data. On Asema IoT Central, both can be defined for objects in three ways to ensure flexibility. These definitions are attached to the object properties in the order of priority:

  1. The quantity and the unit can be explicitly specified in the object schema. If so, this is the highest priority preferred definition.

  2. If the predicate is included a) in a standard SmartAPI ontology OR b) an ontology specified in the object schema, and the quantity and unit are defined in the schema to belong to this particular predicate, then the quantity and unit set as default in that ontology are used.

  3. If the predicate is entered under the Semantic data section of Asema IoT Central System setup, then the quantity and unit found there is used.

  4. If the predicate is not found in any of the explicit designs listed above, quantity and unit are left unset.

8.6. Fine-tuning how trading is done

8.6.1. Adjusting trading settings

Trading settings define how offers, accounts and contracts are handled. Go to Sharing > Trading settings to choose the options:

  • Account location.

    You can choose where your account details are saved:

    Peer-to-peer — The buyer sends the account request with account details directly to the seller.

    Centralized — Account details are stored on a server and accessed by the seller.

    Blockchain — Account details are stored online to be spread in a blockchain.

  • Accept incoming offers.

    Set the way you accept paid offers. There options are:

    Accept automatically until account limit reached — Accept all offers until you reach the credit limit.

    Accept automatically without limit — Accept all offers whatever the account balance is.

    Always ask for manual confirmation — Ask to confirm the offer acceptance.

    Deny automatically — Deny all paid offers.

  • Automatic accounts.

    If you allow creating buyer accounts automatically, specify if you require the buyer's user credentials for it.

    Allow creating a username and an account for requests that have no credentials — Create a buyer's account automatically even if the user didn't send credentials.

    Allow creating an account for requests with proper credentials — Create a buyer's account automatically only if the user sends credentials.

  • Automatic offers.

    Allow creating an offer when no previous account existed — Automatically send an offer together with the account information when you receive a request from a new buyer. This setting works if you set up automatic account creation.

  • Assume resources are free.

    Allow creating a free offer for a shared object that has no offer defined — Share objects that have to offer for free automatically.

  • Offer notarization.

    Notarize each offer accepted by a buyer at transaction server — When the parties of a sharing transaction exchange data, the seller party will send an offer to the buyer for signing. The buyer attaches a digital signature to it as a sign of accepting the offer. While this procedure ensures the seller that the buyer has not forged anything, it still leaves open the possibility of repudiating the transaction. The buyer could for instance claim that the offer was not made at the claimed time. To prevent this scenario, a trusted third party i.e. a notary can be used. The notary will additionally sign the transaction and leave a mark of it into its notary bookkeeping. If both parties trust the notary, then this record can be used to negate any claims of not actually being a part of a transaction.

  • Automatic account starting credit balance.

    Specify the amount to put on the buyer's account when it is created.

  • Subscriptions.

    Deduct account balance at start of each subscription period — If a shared object is paid per period, deduct the fee when the period starts.

    Deduct account balance at end of each subscription period — If a shared object is paid per period, deduct the fee when the period ends.

8.6.2. Adjusting access control for shared objects

To configure access to the objects you share, go to Sharing > Access control. Fill in the fields:

  • Allowed methods — Authorization method to use for accessing the object: session key, username and password, OAuth key.

  • Allow creating new users for shared objects anonymously — Create credentials for new users requesting an offer automatically.

  • Key handling — Whether you want a third side server to notarize the contracts to prevent contract repudiation.

  • Other APIs — Whether API access to objects should be automatically locked when sharing is on.

8.7. Tracking and limiting expenditure

To manage your spendings and set limits on them, go to your purchase account settings.

You might consider having multiple purchase accounts, one account per each system where you buy from. It helps you set limits for your transactions per each seller.

Note

Asema IoT Central isn't integrated with any internet banking system. Accounts are used to keep track of payments and set the limits when buying or selling objects.

To set up your purchase account, go to Sharing > Accounts > Purchase accounts. Click the plus button and then the gear button in the Purchase accounts list. Fill in the fields:

  • Minimum balance — The minimum amount of funds that must be left on account after a payment.

  • Maximum balance — The maximum amount of funds that the account may hold.

  • Credit limit — The maximum amount the balance can be on negative ("on credit").

  • Relaxed limits — Whether it is possible to exceed credit limit and go under the minimum balance.

Chapter 9. Pricing

Pricing is the process of assigning a price to some action or entity represented by an object. A price in Asema IoT can be informative, i.e. used as a label for information purposes, or enforced, i.e. object access is not possible without pay.

An object in Asema IoT Central can be assigned three prices simultaneously, one of them is informative and the other two are enforced:

  • Informative price. This is the price that is "in the price tag" and displayed when someone inquires information about the object.

    You can think of an informative price as something similar to a price tag. The tag is attached to a product but its purpose is only to display the price. It is the cashier that actually ensures that payment takes place in the indicated amount. The informative price is specified in the object property called "cost" which the applications can display.

  • Enforced prices are used in sharing. When you create an offer and someone subscribes to the object, the system monitors that the offers are accepted each time data exchange takes place. If acceptance is not received, the access is blocked. The enforced price can be assigned at two stages:

    • The offered price. This is a price given to someone who asks to do something with the object. The offered price is most often the same as the informative price but not necessarily. There could for instance be an informative price used for direct physical interaction with the system and a separate offered price for the automated online access.

    • The agreed on price. This is the price valid between the publisher and a specific subscriber. While the indicative and offered prices are shown to everyone, special "deals" may be made with selected parties. The offering protocol of Asema IoT Central supports setting prices per requester and also negotiating ("bargaining") a price.

To illustrate the difference between those types, one could say take for instance the following example: "Apples cost 2.0 euros per kilo in general (informative price), but if you order early on Monday morning, you can buy at 1.8 euros per kilo (offered price) and we've made a deal with Danielle that she can buy them for 1.6 euros per kilo (agreed on price)."

9.1. Pricing models

For each type of price (indicative, offered, agreed on), you can further choose among three primary pricing models:

  • Unit price, i.e. a single fixed price that is charged every time on each action. This is the simplest form of pricing. For some action or object A you charge a price P. For example: "50 cents every time the door is opened".

  • Subscription, i.e. a fixed cost for a given period that is independent of the number of actions. Equally straight forward, this is the price P for some time period T. For example: "Access through the door costs 10 euros per month".

  • Price list, i.e. a variable definition of prices that are valid under different conditions. With price lists you can extend the pricing capabilities with pretty much indefinite ways. Price lists contain various conditions that make the price change depending on circumstances. For example: "Access is free until 9 pm but costs one euro per each door unlocking from 9 pm until 6 am". A price list is composed as a combination of various components that influence the final price.

9.2. Assigning prices to objects

How to assign a price to an object depends on the type of price and type of pricing model you want to employ. Assigning an informative unit price or subscription price is easy: simply go to Objects > Configure, click on the setup icon to open pricing and type in the price you want. Alternatively, if you need to edit a large number of prices, open Pricing > Object prices. Here yo use all prices in a table that is quick to review and edit.

To assign an offered price, you need to enable sharing for the object. In Sharing > Publish/sell select a local resource available for sharing and then click the icon to make an offer. Now you can enter the price of the offer. Note that if you have already entered an informative price for this object, it will be suggested as the default but you can override that suggestion if needed.

You can use price lists for both informative prices and offered prices. However, in order to select a price list you need to create one first. This process is explained in the next section below.

9.3. Creating a price list

A price list is a collection of price components; the eventual price is the sum of all the components. Each component influences the price in the particular manner that is programmed to the component.

The primary input for each component is time. This is the most basic type of pricing as it refers to the moment of trade i.e. "what is the price of this thing now". In addition to time, the component may take into account various other factors such as locations, distances traveled, environmental factors, etc. With such inputs, some components may contribute to the total price by setting the component price to some value, while others may keep that particular component at zero under the circumstances given. The combination is then the dynamic price with all aspects priced in.

A common way of pricing something is to have some base price and then add a variable, circumstances-specific component on top. The price list is therefore a sum of two components: one fixed and one variable. Let's take an example. You'd like to sell ice cream so that the price depends on the weather. If it is rainy and cold, the product is sold at discount. However, to cover the cost of the product and sales, you'd still want at least 3.0 euros per each sale. For this purpose, use a base component that is always 3.0 euros. Then add a variable component on top. Say 0 euros when temperature is below 10 degrees centigrade, 2.0 euros when it is below 20 degrees and 2.5 euros otherwise. Now the total price of the ice cream will vary between 3.0 and 5.5 euros depending on weather.

So, to create a price list:

  1. Create a set of components.

  2. Assemble components into a list.

9.3.1. Creating a price component

To create a component, go to Pricing > Price components. Here, select the type of component you want, select it and click on the plus icon in the table that lists the components. A new entry is added to the list. Then click on the edit icon to edit the component.

There are four types of components available:

  • Time-dependent.

  • Location-dependent.

  • Property-dependent.

  • Population-dependent.

  • Scripted prices.

Each of these is explained in the following chapters.

9.3.2. Assembling components into a price list

Once you have one or more components, assemble them into a price list. To do so, go to Pricing > Price lists section. Here, add a new entry to the list of price lists and click on the gear icon to edit. Then enter the price list name and components to include in it.

To help in authoring the price list, you can simulate how it would look like in a given time period. Click Simulate and adjust the period you'd like to see the price list in. Note how each component contributes to the sum.

Note

Note that you can have the same component in several price lists.

9.4. Time-dependent price component

Time-dependent components sets the price that varies over time, changing the price each hour. This schedule of hours can repeat, having a daily schedule, a weekly schedule, or a combination of these. To create a time-dependent component:

  1. Go to Pricing > Price components > Time-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Enter the component name.

  3. To specify the price variations during the day, click Add daily tariff. Specify the starting date and enter the price level for different hours.

  4. To specify the price variations during the week, click Add weekly tariff. Specify the starting date and enter the price level for days and certain hours within the day.

  5. You can view the price levels over time on the bar graph and estimate the revenue. To do it, click Visualize and estimate the revenue. Then enter the forecast length starting from the current moment and the estimated number of transactions per hour in the Est transactions field.

  6. Save the component.

You can now create a price list based on the component you made.

Important

You should always start each pricing schedule from midnight (00:00) onwards. Otherwise the beginning of the price list would be undefined. Then list the subsequent changes in price in chronological order.

9.5. Location-dependent component

Location-dependent components adjust prices dependent on some geographical variable such as position on map or distance. Location-dependent components are useful when you want to set the price based on traveled distance, time used for traveling or visited travel zones. A common example of location-dependent pricing is fare zones used in public transport.

There are several subtypes of location-dependent components. In many of them, you can set the price that increases (or decreases) linearly or define the price intervals (steps). In linear pricing the price changes linearly compared to the measured geographical variable. For example, the price for driving a rental car could be X euros per kilometre. The price increases linearly as the number of kilometres increases. Usually you also have a constant base component. So the rental price of a car could be 35 euros (the base) + 0.5 euros per kilometre (the linear multiplier).

With steps, the price does not increase linearly but at set intervals. For example, the rental car could cost 5 euros for up to 20 km, 7 euros for up to 50 km, and 10 euros (plus gas) for trips over 50 km.

Important

The unit of measurement in all location-dependent components is meters and the granularity one meter. That is, if you for instance create a component that depends on a distance, the price changes each meter and is multiplied by the number of meters.

Let's take a closer look at the various subtypes next.

9.5.1. Distance from center point, linear

This price component changes depending on a distance of an object from a given point on a map. The price is set linearly, that is, it changes equally with every meter. An example: the cost of renting a kayak increases by the farthest point you went to during the rental period.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Distance from center point, linear".

    • Center point – Center point from where the distance is calculated (enter the coordinates or choose the point on the map).

    • Base price – Base component in currency for using the object. If you don't need a base component, set it to zero.

    • Multiplier – Price per meter added to the base price (in currency).

  3. Save the component.

You can now create a price list based on the component you made.

9.5.2. Distance from the center point, steps

This component is similar to the previous one: it charges the user based on how far they are from the specified point. The difference is that you can set the price per distance interval. For example, if you rent a kayak and the farthest point is less than 1000 meters away, the rental cost is 10 euro, if you take the kayak between 1000 to 3000 meters away, the rental is 12 euro, and starting from 3000 meters the rental price is 15 euro.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Distance from center point, steps".

    • Center point – Center point from where the distance is counted (enter the coordinates or choose the point on the map).

    • Limits – Price in currency for using the object. Set the distance intervals in meters and the price for each of them in currency.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.3. Time spent at distance, linear

This component allows you to set the price for using the object based on how much time the object spends at some distance from the point. The price increases linearly with every hour. So for instance, renting a kayak costs 5 euros per hour if the farthest point is 1000 meters from the rental shop and 6 euros per hour if the farthest point is more than 1000 meters from the rental shop.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Time spent at distance, linear".

    • Center point – Center point from where the distance is counted (enter the coordinates or choose the point on the map).

    • Base price – Base price for using the object. If you don't need it, set it to zero.

    • Multiplier

  3. Save the component.

You can now create a price list based on the component you made.

9.5.4. Time spent at distance, steps

This component is similar to the previous one: it charges the user for using the object based on how much time the an object spends at some distance from the point. The difference is that you can set the price depending on the time-at-distance intervals. For example, the rental of a kayak costs 10 euros for up to 3 hours at a distance up to 500 meters, 15 euros per hour for 3 to 10 hours at the same distance, and 20 euros per hour at any distance more than 500 meters from the rental store.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Time spent at distance, steps".

    • Center point – Center point from where the distance is counted (enter the coordinates or choose the point on the map).

    • Limits – Price in currency for using the object. Set the time and distance conditions and the price for each interval in euro.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.5. Travel distance from point A to point B, linear

This component allows you to set the price for traveling between two points. The price increases linearly with every meter. Point A is always the origin i.e. the place where the object is when a price is calculated and point B is the destination. So if the distance from current position (A) to destination (B) is 1500 meters and the price per meter has been set to 0.1 euros, the cost charged will be 1500*0.1 = 150 euros.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel distance from point A to point B, linear".

    • Base price – Base price in currency for using the object. If you don't need a base, set it to zero.

    • Multiplier – Price per meter added to the base price (in currency).

  3. Save the component.

You can now create a price list based on the component you made.

9.5.6. Travel distance from point A to point B, steps

This component is similar to the previous one: it lets you set the price for the traveled distance where point a is the current location and point B is the destination. The difference is that you can set the price for the distance intervals. For example, travelling up to 10 km from the starting point is 5 euro, a distance of up to 20 kilometer costs 8 euro, more than 20 kilometers costs 15 euro.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel distance from point A to point B, steps".

    • Limits – Price in euros for using the object. Set the distance intervals and the price for each interval in euro.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.7. Travel time from point A to point B, linear

This component allows you to set the price based on duration of travel from current location to some destination. For example, if shipping cargo to some port takes several days, a parcel could be priced at 5 euro per day for short distances and 25 euro per week for longer distances. Alternatively, you might want to apply another strategy, setting a price for the first day and then a bit lower price for every following day.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel time from point A to point B, linear".

    • Durations – Price in currency per time.

      For the first example above, the settings are: "When the time traveled is 1 day, price is 0, plus time x 5" and "When the time traveled is 1 week, price is 0, plus time x 25".

      For the second example, the settings are: "When the time traveled is 1 day, price is 5, plus time x 4". Thus, the price for one day would be 5 euro, for two days – 9 euro, for three days – 13 euro, and so on.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.8. Travel time from point A to point B, steps

This component allows you to set the price based on the distance travelled within a certain period of time.

To add the component:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel time from point A to point B, steps".

    • Price intervals.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.9. Located at zone

"Located in zone" component simply sets a price depending on where the object is located at the time of price request. Each zone has a specific price. Such pricing could be used, for example, for pizza delivery. If you order pizza to delivery zone A, it could cost 5 euros per delivery. Zone B is 6 euros per delivery and zone C is 8 euros per delivery.

To set up this component, you need to create zones first (go to Objects > Zones to do it). Then, do the following:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Located at zone".

    • Zones – Choose a zone and enter the price for it.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.10. Travel distance from zone ZA to zone ZB

This component is another variant of zone pricing. It assumes that the object in case moves from one zone to another. A typical example of such pricing would be a toll road, where the users pay depending on how many road sections they need to pass. Public transport also commonly uses this type of pricing for single trips. So taking a metro from Zone A to Zone C will cost a different amount than from Zone B to Zone C.

To set up this component, you need to create zones first (go to Objects > Zones to do it). Then do the following:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel distance from zone ZA to zone ZB".

    • Zones – Enter the prices for visiting one or more zones.

      As an example, imagine a toll road with three sections. The price for driving Central section is 12 euro, driving the Northern or the Southern section costs 10 euro. For two sections, you want to charge 21 euro. So, the pricing would be: "When the Central zone is used, the price is 12", "When the Northern zone is used, the price is 10", "When Central and Northern zones are used, the price is 21", and so on.

  3. Save the component.

You can now create a price list based on the component you made.

9.5.11. Travel time from zone ZA to zone ZB

This component sets the price for zones visited in a certain time period. Such pricing is often used in travel cards for public transport, with for example travel cards for one, two or three zones valid for a certain period of time (an hour, a day, a month).

To set up this component, you need to create zones first (go to Objects > Zones to do it). Then do the following:

  1. Go to Pricing > Price components > Location-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Type of price – "Travel time from zone ZA to zone ZB".

    • Durations – Enter the prices for visiting one or more zones within a certain period.

      For example, "When travel time is smaller or equal then 60 minutes, and zones visited during it are Helsinki and Vantaa, the price is 4.2 euro".

  3. Save the component.

You can now create a price list based on the component you made.

9.6. Property-dependent component

Property-dependent are prices that are tied to the values of properties of objects. The object and property can be freely chosen, as long as the value is something numeric that can be used for calculation. Example properties could be for example measurement values (temperature, pollution, speed, etc), counters (number of seats, number of items in warehouse) or any similar values. For example, you could sell seats to a bus or a cinema based on how crowded it is. Say, the first 20 tickets can be sold for 5 euro, the next 20 for 6 euro and the last 20 ones for 7 euro.

To add the component:

  1. Go to Pricing > Price components > Property-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Object – The object which property is used for the price calculation.

    • Property – The object property to use for the price calculation.

  3. Define what to do if the object property value is unavailable for a particular requested period:

    • Set price to zero (resulting price will be zero)
    • Set property to zero (resulting price will be whatever the price has been set for property value zero)
    • Take property value from previous (property value will be the same as that of the last found property value and the price is set accordingly)
  4. Set the price intervals.

  5. Save the component.

When you design this price component, it may be useful to see what the pricing would look like assuming pricing is calculated with the property values that have already been recorded. This will visualize how your pricing design will behave under known conditions. To do the visualization, click Visualize and estimate revenue to view the graph of known property values in the past and the corresponding prices.

You can also estimate what the pricing will look in the future by applying a forecaster to the recorded values. This will give you a prediction of the prices in the future and, consequently, also the pricing.

To make a prediction, select the timespan for the graph. Anything in the past will be fetched from the database of recorded values, anything in the future is a prediction based on those values.

Next, choose the Forecaster type. This will determine exactly how the prediction is made. You can freely play around with the prediction by changing both the forecaster type and the parameters to it. For a detailed explanation on how each of the forecasters work, please see 16, Forecasting and optimizing.

9.7. Population-dependent component

Population-dependent components change their price depending on how many objects of a particular type occupy a given zone. These components are useful for instance when you need to create a tariff that takes into account "rush hours". For example, you can set the price of a road toll depending on how crowded the road is.

This component uses location data tracked from objects and stored into the database of the system. Note that all objects that are to be taken into account in the calculation must have their location tracking on and must be entered as objects into the Asema IoT Central object configuration.

To set up this component, you need to create zones first (go to Objects > Zones to do it). Then do the following:

  1. Go to Pricing > Price components > Population-dependent. Click "plus" to create a component and the gear icon to edit its properties.

  2. Fill in the fields:

    • Name – The component name.

    • Zone – The zone in which the objects are counted.

    • Type of price – The pattern of how the price changes depending on the number of objects in the zone.

      For the linear pattern, fill in the Base price in currency for using the object (if needed) and the Multiplier per object used to increase/ decrease the price if there are any objects in the zone.

      For the steps pattern, add the price intervals.

  3. Save the component.

You can now create a price list based on the component you made.

9.8. Scripted prices

Scripted prices allow you to program a completely custom pricing model using JavaScript. The concept is straghtforward: whenever the system needs a price for a particular object at a particular time, it will ask for that from the script which should return it. How that price is calculated is completely up to you.

A scripted price is a RuleScript, meaning it can use the same API features as a rule script. The script is loaded into memory and therefore also able to retain state between requests for the price.

Let's look at a sample of a scripted price

import RuleEngine 1.0

RuleScript {
    function getPrice(time)
    {
        var hour = time.getHours();
        var base = 0;
        if (hour < 4) base = 10;
        else if (hour < 4) base = 10;
        else if (hour < 10) base = 100;
        else if (hour < 13) base = 200;
        else if (hour < 22) base = 230;
        else base = 150;
        return base + Math.random()*100;
    }
}
      

Each pricing script must have one method: getPrice(). This method takes one argument, the timestamp, which is a JavaScript Date. The method should return one value, the price. What happens in between is up to the programmer. The sample generates a base value depending on the hour of the time given and adds a random component to it.

Optionally, you may include another method in the script: init(terms). This method is guaranteed to run immediately after the script is called the first time (the script is then cached and will not get any subsequent calls to init()). As the name implies, the purpose of this method is to have all the initialization procedures whose output subsequent calls may want to use. init()) is automatically given one argument of type map (dictionary). This map contains any object specific pricing terms and configuration that may have been inputted. If no specific configuration exists, the map is empty. With the terms parameter you can control your pricing script individually per each object and give it any freeform parameters it may require.

Note

Note that the terms parameter is object specific and therefore there must be an object bound to the component. In some features of the system such as simulation of prices during design phase, this is not possible because at design stage there is not yet any object assignment. Take this into account as your pricing may behave differenly in simulation and in actual price assignment if terms are added to the object pricing.

Because the pricing script is a rule script, it can load objects into memory the same way as rules would. And this makes it possible to create very rich and dynamic pricing logic based on properties. Below is an example:

import RuleEngine 1.0

RuleScript {
    property variant element: null
    
    function onLoadedObjectsReady(propertyName) {
        if (propertyName == "weather") {
             element = context.objects.weather.list[0];
        }
    }
    
    function init() {
        context.objectsReady.connect(onLoadedObjectsReady);
        objectContext.findObjectByComponentId(context, "weather", "weatherstation");
        return true;
    }
    
    function getPrice(time)
    {
        var temperature = 0;
        if (element != null && element.properties.temperature != undefined) {
            temperature = element.properties.temperature;
        }
        var hour = time.getHours();
        var base = 0;
        if (hour < 12) base = 10;
        else base = 20;
        return base + temperature * 10;
    }
}
       

This example loads an object (in this case a "weather station") into memory and uses the properties of that object as a basis for pricing. If the object is loaded, each call to getPrice() will fetch the latest temperature value of the weather station, add a variable time component (either 10 or 20) and then add the temperature multiplied by 10 as the final price.

As there is no limit to how many objects are loaded and used in pricing, this method makes it possible to perform various kinds of cross-correlating prices between objects dynamically and generate the prices with them.

Chapter 10. Managing content

The Asema IoT Central features an article-based content management system (CMS) to allow authoring custom content to places where IoT data is displayed. The purpose of the CMS is to provide tools for adding human input such as news, announcements and similar into the visuals. This way, when Asema IoT Central is used to display data in a public location such as a lobby, the same screen can also be used as a bulletin board.

The CMS editing functionality is available in the Content section of Asema IoT Central browser interface. To display these announcements, the main GUI of Asema IoT Central must be turned into CMS view.

You can add various kinds of content to use in your Asema IoT Central applications:

  • Announcements (news snippets, bulletins, postings and so on) that you can show, for example, on displays where Asema IoT Central runs. Announcements appear on the CMS view of the Asema IoT Central desktop interface.

  • Messages that can be sent and received by the users.

  • Instructions to use in Asema IoT Dashboard app for deployment of remote objects.

  • Events that take place in a certain location and can be displayed on a map.

  • Tasks that you can assign to users and track for completion.

  • Points of interest, or locations marked on the map.

  • Map lines you can use to mark roads, pipelines on the map.

  • Map areas of any shape.

  • Spaces that are similar to map areas, but designed for a certain purpose (for example, parking spots).

  • Layers with pictures, schematics and drawings that can be projected on a map.

10.1. Announcements

An announcement contains a title and text. You can set the time period when it is shown on the user screens. The way the announcement is displayed on the CMS view will depend on a template that renders it. For more info on templates, see 11.4, “CMS templates”

To add an announcement, go to Content > Announcements and click Add new. Enter the validity period, the title and the message and click Save.

To remove an announcement, choose it for editing and click Delete.

Note

If you set a validity period for an announcement, it is removed from the user interface once the validity period expires. It isn't however removed from the system until deleted as explained above.

10.2. Messages

Messaging is meant for quick communication between Asema IoT Central users. It includes basic functionality to allow the users exchange messages within the system.

Messages can currently be sent only between the users of the same Asema IoT instance.

There are two types of messages, normal messages and alerts. If you mark a message as alert, it is shown in a separate box on the recipient's Asema IoT Central dashboard.

To send a message, go to Content > Messages and click Add new, then choose a recipient, specify the message type, add the message subject and content. Then click Send.

Received messages are shown to the recipients on the Asema IoT Central dashboard. From here they can be read, replied to, and deleted using the respective icons.

Sent messages aren't saved.

Note

Messages in Asema IoT are meant for quick messaging between system users. You cannot forward messages to an external messaging system such as email simply because they are meant only for quick, integrated communication between users. If more comprehensive messaging is needed, there are dozens of very polished and effective solutions available in other services and software.

10.3. Instructions

Instructions are text documents that are attached to tasks to help in performing them. The concept of an instruction is simple: it is just an authored text document that describes some task. When you enter a task (see below) into the system, you can then link the instructions to that task.

Instructions are also an integral part of device deployment. For more info on deployment, see deployment of remote devices. When field engineers are installing new equipment, they can use the Asema IoT Dashboard mobile app to help in the process and will receive the instructions to their devices to help in e.g. configuration tasks.

10.4. Events

Events take place at a certain time and location. They can be placed on a map (for example, in an application).

To create an event, go to Content > Events and click Add new. Enter the event name, description, time period and type (the latter works as a tag shown with the event).

10.5. Tasks

Tasks are similar to messages, they are created to assign duties to users. A task can be linked to a certain event. For example, if there is an event "Electricity went off", you can link it to a task "Fix the electricity issue" and assign the task to some user. You can then track the task for completion.

To create a task, go to Content > Tasks and click Add New. Then fill in the fields (Name and Planned start are mandatory) and click Save.

Created tasks are shown to the assignees on the Asema IoT Central dashboard.

10.6. Points of interest

Points of interests are places marked on the map.

To create a point of interest, go to Content > Points of interest and click Add new. Enter name and description and choose the place on the map. Click Save.

10.7. Map lines

Map lines can be used to mark such items as roads, pipelines on the map.

To create a map line, go to Content > Map lines and click Add new. Enter the name, draw the line and click Save.

10.8. Map areas

Maps areas can be used, for example, to set boundaries for data collection.

To create a map area, go to Content > Map areas and click Add new. Enter the name, draw the area and click Save.

10.9. Spaces

Space on the map are similar to boundaries, but they have certain shape. Currently, the following shapes are available:

  • Parking spots.

  • Diagonal parking.

  • Bus stop.

  • Tram stop.

To create a space, go to Content > Spaces and click Add new. Enter the name, choose the shape and click Save.You can move the created spaces on the map and rotate them with arrow buttons. For parking spaces, you can add or remove rows and columns with the Add row, Remove row, Add column, Remove column buttons.

10.10. Custom maps and layers

Custom maps and layers are custom images that you can place on top of the map, for example, 3D outlines of buildings. To do it, go to Content > Layers and click Add new. Move, stretch and rotate the item on the map to put it in the right position.

Chapter 11. Customizing and managing visuals

If you have public displays with any kind of information (timetables, announcements, adverts) connected to Asema IoT Central, you can customize and manage the screen view on those displays from the Asema IoT Central web interface.

With your Asema IoT Central application, you can:

11.1. Screen view

To manage the screen view, go to the Visuals > Settings. You can:

  • Switch the view mode:

    Grid — Screenlets arranged in a grid.

    Carousel — One active screenlet expanded on the screen, with a scrollable row of screenlets on the right. You can choose a screenlet expanded by default (the Default screenlet field).

    Content — Screenlets shown one after another, with an icon bar at the bottom of the screen. With Content view, you can use the following view options:

    • Choose a screenlet expanded by default (the Default screenlet field).

    • Specify how long a screenlet is shown (enter the time in seconds in the Content view transition time field).

    • Set the way the screenlets change (the Content view transition field).

  • Toggle fullscreen mode (the View fullscreen / View windowed radio buttons).

  • Add a bottom bar with sensor display (the Bottom bar visible/ Bottom bar hidden radio buttons)

  • Add a bottom bar with an RSS feed. To do it, choose the Bottom bar visible and RSS Ticker options. Then enter the RSS URL in the Bottom bar RSS URL field).

11.2. Video streaming

Video streaming lets you use Asema IoT as a source of a video feed over the network. For example, you can add surveillance camera feeds to the monitoring dashboards, stream views from remote operated vehicles, or use cameras to monitor remotely operated devices.

Asema IoT Central supports two modes of video capture:

  • Recording to a file
  • Real-time streaming to a server

11.2.1. Recording to a file

To record video to a file, supply a path to the .mp4 file to save the video to (for example, /home/<user>/iot_lab_recording.mp4) and click Start stream. To end the recording, click Stop stream.

Important

Note that there is no upper limit set to the file size. If you leave the recording on, it may eventually fill up the disk.

11.2.2. Real-time streaming to a server

To stream a video, you need to set up a streaming server somewhere, either on the same server where Asema IoT runs or some other server, as Asema IoT Central is not a streaming server itself.

Asema IoT currently supports ffserver It is an open source, free streaming server available for Linux and OSX operating systems, and there are some unofficial builds for Windows.

To set up video streaming:

  1. Configure a streaming server.

    Create a configuration file ffserver.conf that defines the input stream and the output stream. Note that the output from Asema IoT Central is in FLV1 (flash video) format. Here is a file sample:

    HTTPPort 8090 
    # bind to all IPs aliased or not 
    HTTPBindAddress 0.0.0.0 
    
    MaxClients 4
    # max bandwidth per-client (kb/s) 
    MaxBandwidth 10000 
    
    <Feed iot.ffm>
     File /tmp/iot.ffm 
     FileMaxSize 5M 
    </Feed>
    
    <Stream iotvideo.swf>
     Feed iot.ffm
     Format swf
     VideoCodec flv
     VideoFrameRate 25
     VideoBufferSize 80000
     VideoBitRate 100
     VideoQMin 1
     VideoQMax 5
     VideoSize 352x288
     PreRoll 0
     Noaudio
    </Stream>
       
  2. Launch the server:

    ffserver -f <path_to_configuration_file>/ffserver.conf
       

    Now you can watch the video stream in a browser at the address http://<server ip>:8090/iotvideo.swf.

  3. In Asema IoT Central, choose Streaming server as an output and enter the output URI. For the configuration above, it would be http://<server ip>:8090/iot.ffm

    .

11.3. Remote control

You can use your IoT Central application no navigate the users' screens remotely. To do this, go to Visuals > Remote control. Use the buttons to move between the screenlets, minimize or expand the screenlets and choose a view mode.

11.4. CMS templates

CMS templates define the look and feel of the CMS (Content Management System) view of Asema IoT Central desktop view. This view is meant as a customizable view to display not only IoT data but also custom authored content.

The CMS view customization can be used to add various functional and graphical elements to the user interface and most importantly to support the brand image of the organization that runs the system. To support such customization and branding (e.g. add a logo, change the color scheme, display images, and so on), you need to write a CMS template and then upload it to the system.

11.4.1. Managing templates

To upload the template, go to Visuals > Templates. Then drag and drop the template to the upload area or alternatively select the file using a file selection dialog.

To delete a template, select it from the Remove existing dropdown and click Delete.

To choose the template that is used in the CMS view, select it from the Current template dropdown. The template will automatically change.

11.4.2. Authoring templates

CMS templates follow the same programming logic and use the same API offered by the system as screenlets do. For in-depth instructions on how this programming works, please refer to 12, Applications and the Asema IoT Application Programming manual.

While the CMS template works like a screenlet, it has one important distinction: it is automatically assigned to the QML ListView that changes the "slides" of content in the view. This is why it has two properties automatically available: modelData.title and modelData.styledContent(). The former carries the title that has been entered into an Announcement created with the web admin interface. The latter has the content, including formatting tags that have been added with the Announcement editor. With these properties, the authored content can be placed inside or fully custom graphic layout.

Let's take a look at an example template:

import QtQuick 2.3
import Jarvis 1.0

Item {
 id: exampleTemplate
 width: screenWidth
 height: screenHeight - bottomBar.height

 Rectangle {
  color: "transparent"
  width: parent.width - 120
  height: parent.height - 50
  x: 60
  y: 30

  Image {
   id: logo
   source: "logo.png"
   anchors.right: parent.right
   anchors.rightMargin: 0
  }
  
  Rectangle {
   id: separator
   width: parent.width
   height: 3
   x: 0
   anchors.top: title.bottom
   anchors.topMargin: 8
   color: "white"
  }
  
  Text {
   id: title
   font.family: "Elektra Text Pro"
   color: "#123456"
   wrapMode: Text.WordWrap
   text: modelData.title
   width: parent.width
   font.pixelSize: 82
   font.bold: true
   anchors.top: logo.bottom
   anchors.topMargin: 20 
   horizontalAlignment: Text.AlignHCenter
  }
  
  Text {
   anchors.top: separator.bottom
   anchors.topMargin: 100
   width: parent.width - 200
   anchors.horizontalCenter: parent.horizontalCenter
   color: "white"
   text: modelData.styledContent()
   textFormat: Text.RichText
   wrapMode: Text.WordWrap
   font.family: "Elektra Text Pro"
   font.pixelSize: 60
   style: Text.Sunken
   styleColor: "#111111"
  }
 }
}
        

The template above will place a logo image at the top righthand corner of the screen, a title at the top and the body text at the bottom. A white separator line is placed below the title.

Because the template runs inside the application engine, you can freely add JavaScript logic code into it. As in the example, the Jarvis library is included also so you can operate on objects as a part of the template and include their data in processing and on screen. For details of how to manipulate the objects, see the programming manual for applications.

Chapter 12. Applications

Applications are the primary means for creating custom logic and look and feel for various IoT solutions. Asema IoT supports generating applications in two formats:

  • Web applications that run on browsers and are ideal for manipulating data stored on a cloud server
  • Native applications (screenlets) that run on mobile devices are ideal for mobile applications and workstations that connect directly to measurement equipment

Note

Programming applications with Asema IoT is a broad topic that is is covered in its own dedicated manual. Please refer to the Asema IoT Central Application programming guide for more info. The following chapter in this manual does not discuss the actual programming of applications but their enrollment and management.

12.1. Web applications

Web applications are one of the most popular ways to take your application to the masses. Creating and managing web applications in Asema IoT Central is relatively simple when done via the admin interface. You can also access the public_html directory of the built in HTML server of Asema IotTCentral to create your files there.

In Linux, the public_html directory is located at

/home/<user>/.local/share/Asema IoT Central for Linux/public_html.

In Windows, you can find it at:

\Users\<user>\AppData\local\Asema IoT Central for Windows\public_html.

All the web applications created via the admin interface are also available at those locations. So, if you need to make any modifications to the application and its constituent files, that is where you will find them. The steps involved in creating and managing web applications are described in the following sections.

Note

The section below assumes that the application mostly runs on the webserver of Asema IoT Central. This may not be the case with applications that utilize some other webserver or application server such as node.js, Apache Tomcat or Microsoft IIS. In such cases Asema IoT Central typically runs in parallel and only provides IoT data management functions. For recommended system configurations in such parallel setups, please see Asema IoT Central Application programming guide.

12.1.1. Creating a web application

This section describes the steps involved in creating a web application with the Asema IoT Central web server:

  1. Go to Applications > Web apps. Enter the application name and click Create.

    This will create a blank new application for you.

  2. Navigate to the public_html directory to make changes to your application files and add the desired functionality.

  3. To access and run the application, click the eye icon next to the app name in Applications > Web apps > Manage existing web applications.

All web applications created via the admin interface are auto deployed in the Asema IoT Central server. Those applications are available in your browser at http://localhost:8080/pub/<application-name> or the equivalent URL of your deployment.

12.1.2. Importing an existing web application

In addition to creating an application from scratch, you can install a previously created web application from a package. To do this:

  1. Go to Applications > Web apps. You will see a drag and drop area on the screen.

  2. Drag and drop your web application package (a .zip file) and click Install to install the application.

    Note

    If you import an application package created with Asema IoT Central (see instructions below), this package has a definition file that names your application automatically.

12.1.3. Exporting an existing web application

To create an installation package of your web application to be imported into some other Asema IoT instance, go to Applications > Web apps and click the gift icon (Create an installation package) in the list of existing applications.

12.1.4. Managing web applications

To manage web applications, go to Applications > Web apps > Manage existing web applications. For each package, you get the following four options:

  • View (the eye icon). This opens a new browser tab to your application URL.

  • Delete (the trash icon). This lets you delete your web applications from the server.

  • Create an installation package (the gift icon).This lets you create installation packages for your web application, so that you can install it on other servers. The created package is in .zip format.

  • Upload a webapp (the upload icon). This lets you upload your application a remote peer.

12.2. Screenlets

Screenlets are widgets or lightweight applications that can be placed on Asema IoT dashboard. They are similar to programming concepts such as "applets" or "widgets" as each of these rely on underlying operating system to offer standardized methods for development, installation, configuration and removal of the program. As they run on device as opposed to browser, screenlets also offer better integration possibilities into the underlying hardware and software.

In Asema IoT Central, screenlets are available from three sources:

  • Global store. This is the app store for screenlets that Asema hosts. The global store is a repository of screenlets from where anyone can browse and install screenlets.

  • Remote store. This lets you install screenlets from connected peers (other Asema IoT instances). Simply choose a network peer and install screenlets from it.

  • Local store. This holds all screenlets that you created in your local machine. When you you create a screenlet, Asema IoT Central creates template with the basic structure for you to edit. And if you want to run a shiny screenlet you created, this is where you will find it. The packages are in .zip format.

The screenlet code is usually written by developer in the Asema IoT Central desktop interface (developer mode). Once the screenlet is ready and published in the stores, it is available for installation. Screenlets can be managed either from the web admin interface or from the desktop interface of Asema IoT Central.

12.2.1. Creating a blank screenlet

Screenlets can be created in either from the web admin interface or from the desktop interface of Asema IoT Central.

To create a screenlet in the Asema IoT Central web admin interface, go to Applications > Screenlet apps > Local store. Enter the screenlet name and click Create. A blank screenlet with the given name is created.

To create a screenlet in the Asema IoT Central desktop interface in the developer mode, click the screenlet management icon in the top bar (second icon from the right). In the Manage tab of the pop up window, enter the screenlet name and click Create. A blank screenlet with the given name is created.

In Linux systems, the screenlets you created are available at

/home/<user>/.local/share/Asema IoT Central for Linux/screenlet_installs/local.

In Windows systems, you can find them at

\Users\<user>\AppData\local\Asema IoT Central for Windows\screenlet_installs\local.

Note

You can also create new screenlets manually by creating subdirectories inside the local screenlet directories mentioned above. The minimal requirement for a working screenlet is that in the directory you must install the basic screenlet template with the name "Screenlet.qml".

12.2.2. Publishing screenlets

To make a screenlet available for installing on other devices running Asema IoT, you can:

  • Publish a screenlet to the global screenlet store. It can then be downloaded by other Asema IoT users or you can download it yourself to some other installation. Publishing to global store is available only from the Asema IoT Central desktop interface (in developer mode).

  • Publish the screenlet to connected peers. This feature is meant for managing autonomous displays such as hotel lobby displays or point-of-sale displays. If an update is needed into the screenlets these screens are showing, the update can simply be remotely pushed onto the screen. Publishing a screenlet for peers is available only in the Asema IoT Central web admin interface.

  • Save the screenlet package (.zip) to install in other Asema IoT systems. Package creation is available only in the Asema IoT Central desktop interface (in developer mode).

To publish a screenlet for connected peers, use the Asema IoT Central web admin interface. Go to Applications > Screenlet apps > Local store. In the existing local screenlets list, click on the Upload icon next to the desired screenlet, select a peer and click Install.

To publish a screenlet in global store, use the Asema IoT Central desktop interface (in developer mode). Open the Manage custom screenlets window using the icon in the top bar. In the Upload tab, select a screenlet to publish and publish the application to the global screenlet store.

To save the screenlet package, use the the Asema IoT Central desktop interface (in developer mode). Open the Manage custom screenlets window using the icon in the top bar. In the Upload tab, select a screenlet to publish and generate a installation package (untick the Upload to server option).

12.2.3. Installing a screenlet

You can install screenlets in the Asema IoT Central web admin interface or in the Asema IoT Central desktop interface (also working in the developer mode).

To install a screenlet in the Asema IoT Central web admin interface, go to Applications > Screenlet apps. Choose a store, and proceed accordingly:

  • Global store: click on install and browse the list to select and install desired screenlet.

  • Remote store: choose a network peer and install screenlets from it. This option is available only in the Asema IoT Central web admin interface.

  • Local store: drag and drop the package (.zip), once the upload completes, click Done to complete the installation process.

To install a screenlet from a global store in the Asema IoT Central desktop interface, click the E button on the top bar to navigate to the main menu. Choose the option to install a screenlet. Note that this works only for global screenlets.

To install a screenlet from the local machine in the Asema IoT Central desktop interface, switch to the developer mode, click the icon on the top bar to open the Manage custom screenlets window. In the Install tab, choose the package to install (.zip).

12.2.4. Managing screenlets

Screenlet management can be done both in the Asema IoT Central web admin interface and in the Asema IoT Central desktop interface (also working in the developer mode). You can uninstall or delete a screenlet.

To manage screenlets in the Asema IoT Central web admin interface, navigate to the desired screenlet store (Applications > Screenlet apps).

To manage screenlets in the Asema IoT Central desktop interface, click the E button on the top bar to navigate to the main menu.

If you are working in the developer mode, click the icon on the top bar to open the Manage custom screenlets window. In the Manage tab, click the screenlet to update or remove.

12.3. Application bundles

Application bundles are packages that contain your Asema IoT Central settings, such as objects, apps and rules. With bundles, you can easily import these settings to another Asema IoT instance.

To create a bundle:

  1. Go to Applications > Application bundles and click Create a bundle.

  2. Choose apps, objects and rules to include in the bundle.

  3. Save the .zip package to your computer.

To install the application bundle, go to Applications > Application bundles, drag and drop the .zip file and click Install.

You will find the apps, objects and rules copied to the Asema IoT Central.

Chapter 13. Generating reports

Reports are static snapshots of object data you can export in suitable format for reading or further processing. Asema IoT Central supports two types of reports: PDF reports and Excel exports.

Note

While the user interface offers two preprogrammed report formats, the JSON API and Smart API both feature timeseries requests that can be used to programmatically fetch data into other applications and report generators.

Excel exports simply give you the historic recorded data of a selected object and its properties in a spreadsheet. The format of these sheets is preprogrammed. PDF reports create a PDF file of some dataset. The functionality needed to create these PDFs are programmed into templates and can therefore contain pretty much any text or graphics.

13.1. Exporting data in Excel spreadsheet format

To generate an Excel spreadsheet of your data:

  1. Go to Objects > Control and monitor, and click the Charts and data button next to the object.

  2. Choose the time period and object properties to include in the spreadsheet and click the Export data button.

13.2. Generating PDF reports

To generate PDF reports with data collected from your objects:

  1. Go to Objects > Control and monitor, and click the Charts and data button next to the object.

  2. Choose the time period and object properties to include in the report, choose the template you want and click the Create a PDF button.

Important

For the system to produce a PDF report, it will need a template for it. If there are no templates in the system, you will not see an option or button to create a PDF report. In this case, first author and install a template.

13.3. Authoring templates for PDF reports

PDF reports use a template which defines the layout of the report as well as any processing to be done with data prior to rendering the PDF file. While the PDF itself is static, the process of generating it is fully programmable in JavaScript.

Templates for PDF reports are uploaded in the Visuals > Templates section of the Asema IoT Central web admin interface.

The template file is programmed in QML/ JavaScript. The QML part defines the graphics and the layout while the JavaScript part fetches data from the system and does any other computational work that may be required. The lifespan of this application is defined as follows:

  • Whenever the report generation starts Asema IoT's application engine will call the render() method of the template.

  • The rest of the template logic will then run with whatever logic has been programmed into it and for as long as it wants, placing text and data into the document.

  • Once the logic is done, it should emit the rendered signal. At this point the application engine will look at the state of the document and output the result into a PDF file accordingly.

Because the rendering process uses the rendered signal, there is no time limit on the functionality and it may run asynchronously. For instance, the template may use the various APIs to fetch data from remote servers and only once the data has arrived and has been placed on the page, the PDF is generated.

As an example, let's take a look at a template that generates a random number, places it on screen and then outputs the result by emitting the rendered signal.

import QtQuick 2.3

Item {
 anchors.fill: parent
 
 property variant context;
 signal rendered;
 
 function render(gid) {
  var rnd =  Math.random() * 100;
  randomNo.text = rnd;
  rendered();
  return "OK";
 }
 
 Text {
  id: titleWText
  text: "My number:"
  anchors.centerIn: parent
  font.bold: true
  font.pixelSize: 16
  color: "#123456"
 }
 
 Text {
  id: randomNo
  text: ""
  anchors.horizontalCenter: parent.horizontalCenter
  anchors.top: titleWText.bottom
  font.bold: true
  font.pixelSize: 20
  color: "black"
 }
}
 

Note

PDF reports are a part of the application programming framework of Asema IoT. To learn more about how to program them as well as an explanation on how the example template works, please refer to 12, Applications and the dedicated Asema IoT Application Programming manual.

Chapter 14. Analysis

14.1. Analysis engine

Data analysis is the process of mathematically calculating and analyzing the collected IoT data. Analysis algorithms can produce new insights into the data or correct the data by applying various correction factors.

The task of analyzing the collected data is performed by the analysis engine of Asema IoT. The engine can be programmed with various algorithms to fetch data from the collected database, perform the operation and return a vector (a series) of values as a response.

Data analysis is typically done by various applications that call the analysis engine. For this purpose each algorithm has a unique identifier. This identifier is used by application programmers to point to the correct algorithm.

The analysis engine offers four distinct ways to define analysis algorithms

  • A graphical algorithm editor. This method defines one chain of mathematical methods to apply to a series of data.

  • A JavaScrit editor. This method makes it possible to freely program the desired algorithm using JavaScript.

  • A connection to R. With this method the data is passed on to the statistics program R, which can then be programmed to process the data.

  • A connection to MATLAB. With this method the data is passed on to MATLAB, which can then be programmed to process the data.

Note

Programming various algorithms and using them in applications is a broad topic that is covered in its dedicated manual. This manual describes how to manage the algorithms i.e. how to add and remove them but does not cover the details of programming them. For a complete look at the details of data analysis, please read the Asema IoT Central Data Analysis Manual.

14.2. Analysis algorithms

Analysis algorithms are a graphical way of defining a chain of mathematical functions. Compared to the other methods, this is the most straightforward. Simply drag and drop pieces onto a canvas and apply.

To create an algorithm, proceed as follows

  1. Open Analysis > Algorithms and click Add new.

  2. In the form that opens, add a descriptive name and a unique identifier (a string that no other algorithm has).

  3. Design the algorithm by clicking on the functions on the left bar, then combine them if you use multiple.

  4. Save the design by clicking Save.

Combining algorithms takes place by pulling the dark blue circular corner of one piece into the light blue rectangular edge of another piece. This procedure means that the first (circular) calculation will be done first, then followed by the second. So if you'd add the piece "Add" and then the piece "Divide", then a number would be added to each piece of data first, then the result of the addition would be divided.

The coefficients of each operator needs to be inputted into the boxes that represent the algorithm pieces. So setting the number 3 into a box that says Multiply would mean each value handled by the algorithm will be multiplied by 3.

14.3. Analysis with JavaScript

With JavaScript, you can program any type of analysis you may find useful with the methods found in JavaScript. Details about programming the scripts are covered in the Asema IoT Data analysis manual, but here's a short brief.

To create a script, proceed as with other algorithms by entering a name and an identifier for your algorithm. Then add a script that imports the AnalysisEngine API and enclose the function within an AnalysisScript structure. The script should have one main method called run() which returns the result of the calculation. Values for the calculation are given to this method.

Below is an example of how one would calculate the average of a set of values.

import AnalysisEngine 1.0

AnalysisScript {
 
 function run(arglist) {
  var result = 0;
  for (var index = 0; index < arglist.length; index++) {
   result += arglist[index];
  }
  return (result / arglist.length);
 }
}
      

14.4. Analysis with R

R can be combined with Asema IoT Central with the so-called R bridge. Once the bridge is in place, the script written in Asema IoT Central will be passed on to R along with the data from the object database.

To be able to use the bridging, you must first set it up. To do so, proceed as described below.

14.4.1. Installing R on Linux

First, you need R, the software itself. In most Linux distributions, R is available in standard or statistics repositories. To install it, consult the manual and the package manager of your Linux for details. For instance, in OpenSuSE, R can be fond in the R-base package in the main repositories and is installed with zypper in R-base. Note that the Rserve extension may need to build against your R installation so you also need the devel (source) packages of R.

Once R is installed, start it. Note that to install Rserve, you need to start R with a user that has the right to install software extensions (usually root). Once you are root, starting R from command prompt is simply:

> R
   

Next, in R, do:

> install.packages("Rserve")

Select an appropriate mirror and let the software download and compile the extension. Then exit R (Ctrl+D).

You can now restart R as a normal user and then start Rserve:

> R
> library(Rserve)
> Rserve()
   

You now have R installed and running.

14.4.2. Testing the R installation

Rserve essentially relays R-command sequences — the R scripts from a remote system (in this case Asema IoT) into the R software. If you are familiar with R, testing the installation simply means running some R script you know and observing the results.

As an example, let's try something simple. In Asema IoT, go to Analysis > R scripts and click Add new". Type the following in the R algorithm field:

(100+2)*3
    

Then click Run in R. You should now get a pop-up that says "306". If it does, your R installation is working fine.

Next, let's try some analysis function. Type the following in the R algorithm field:

data <- c(10,10,10,20,30,40,50,50,50,50)
hist(data)
    

And again click Run in R. In the pop-up, you should get various details of the histogram of those values, such as unique number present and histogram bucket sizes.

14.4.3. Processing data with input vectors

Now that R is up and running, it is time to do some actual number crunching. The standard way to do this is to feed into R some set of timeseries data. Do extract some, you add an input vector.

Important

Note that while you can put in data to R scripts with fixed input vectors, you can also use dynamic data input with R scripts in addition to this, just like with other means data analysis.

Input vectors are located in the table just above your R script. You can have multiple of them and assign each into a separate variable. To edit, click on the editing icon. In the editor you can choose the object and the property to have the data of as well as the time range.

Most importantly, here you will define the Assigned variable. This is the variable name you use to access the vector in the R script. So if you add a variable called "rawTemperature", you can then directly feed this into the functions of R as a vector. For instance, to draw a histogram of rawTemperature, in your script you'd say hist(rawTemperature). Every time you invoke the analyzer, Asema IoT will fetch fresh values from the database into the vector.

14.5. Analysis with MATLAB

Asema IoT Central can also perform data analysis by using MATLAB as the analysis engine. In this process Asema IoT Central sends its data as an iput vector to MATLAB which needs to run a specific server process that listens to the calls. This server process will then pick the appropriate MATLAB function file (.m), feed data to it, and return results back to the caller.

To be able to use this analysis feature, you must first set up MATLAB correctly. To do so, proceed as described below.

14.5.1. Installing and configuring MATLAB

Asema IoT Central communicates with MATLAB over the ZeroMQ (a.k.a. ZMQ or 0MQ) protocol. ZMQ hooks are in the messenger MATLAB extension binary (mex) which you need to compile on your workstation / server. You will find the sources of the messenger package in the downloads section of Asema IoT Central software. This package will also contain the other necessary files such as the matlabserver.m file which you need to run on MATLAB once installation is done.

Note that these instructions are for Linux workstations. The procedure should be similar on other platforms and should work but is however not covered in this manual.

To compile the messenger and install ZMQ support into MATLAB as the parser for the protocol payloads, first download the messenger source and then proceed as follows:

  1. Install ZMQ development packages. This will also install the required ZMQ binary libraries into your workstation. The installation method depends on your operating system and package management. Example on SuSE Linux:
    zypper in zeromq-devel
            
  2. Build the messenger. This is the binary file that runs and parses ZMQ.
    cd messenger
    python make.py matlab
            
  3. Copy the messenger in place. The messenger is a mex file so MATLAB will try to find it starting from current path and then going through the search path. More info on search paths can be found here: https://se.mathworks.com/help/matlab/matlab_env/files-and-folders-that-matlab-accesses.html. An easy way to determine a proper location is to start MATLAB, then type
    >> userpath
            
    Copy the messenger mex file to the path shown by this command.
  4. Install the server MATLAB script matlabserver.m into a location where you'll find it.
  5. Install the utility and user programs under usrprog and util to a location where MATLAB finds them, e.g. the userpath.
  6. Start MATLAB.
  7. In MATLAB, start the server
    >> matlabserver <address>
            

Important

The MATLAB address you enter when starting matlabserver.m must match the address that Asema IoT Central will contact when it wants to run an analysis with MATLAB. The default address to use is tcp://127.0.0.1:8899.

14.5.2. Debugging and testing the MATLAB setup

Asema IoT Central's debugging output includes the data transmitted from and to MATLAB. To view this output either

  • Start Asema IoT Central with the -N flag with debug level at at least 2 (i.e. -N 2); or
  • Set the debug level from system settings at System > Logging and console to "Detailed"

When you run any MATLAB algorithm with debugging on, you will see whether MATLAB responds to your queries and any errors that MATLAB may produce. If

  • you only see messages being sent but none received, check that the bridge address has been set to be the same both in Asema IoT Central and MATLAB, that MATLAB is running and that you have installer the messengermex file into MATLAB
  • you receive errors as a response, make sure you have installed the correct version of matlabserver.m into MATLAB and that it is running
  • you receive an error that the function processor is not working, ensure you have installed all the files under usrprog (and especially test_sum.m) into a location where MATLAB can find them.
  • you receive an error that the algorithm you are trying to run cannot be found in MATLAB, make sure you have authored the corresponding .m file and it is in a location where MATLAB can find it

To make a simple test run, create a MATLAB algorithm in Asema IoT Central and click Run in MATLAB. You will get a pop-up with the result or an error message from MATLAB, if your .m file doesn't exist or doesn't accept the input.

14.5.3. Processing data with input vectors

You can feed data from your IoT objects to MATLAB with the help of input vectors. To add an input vector, go to Analysis > MATLAB and open your MATLAB algorithm script. You can have multiple vectors and assign each one a separate variable. For each vector, choose the object and the property you wish to have the data of as well as the time range.

Chapter 15. Rule automation

The rule engine lets you automate the system's operation. The basic concept of a rule is straightforward: each rule says that if an event takes place, then perform an action. Once started, rules "run" inside the rule engine i.e. are evaluated automatically without further interaction. All you have to do is to specify what has to be done in particular situations. For example, "If it is sunset, turn on the lights" or "If the temperature is below 18 degrees, turn on the heating", or "If the parking price drops to 1 euro per hour, send me an email".

As you can see from the examples, a rule consists of two parts, the condition ("if") and the consequence ("then"). Building rules means designing both conditions and consequences and then linking them together. When conditions and consequences are linked, conditions send signals to consequences. A condition that becomes true (or false if it is a negated condition) is said to trigger. This triggering causes either a true or false signal to be sent. The consequence is then set up to react to that particular signal.

Depending on the complexity of the rule you need to compose, you can use one of the tools:

  • Standard rules with boolean logic. These rules are built from ready-made blocks in the Asema IoT web admin interface.

  • Custom rules. These rules can have more complex logic and are programmed with JavaScript.

15.1. Standard rules

A standard rule in the Asema IoT engine has two basic components:

  • Conditions, i.e. the condition that triggers the rule. There are several types of conditions

    • Timer conditions — set the time to perform an action.

    • Property conditions — set the threshold value of the object property (for example, "if the unit temperature rises to 60 degrees").

    • Tariff conditions — set the price threshold (for example, "if the price goes under 5 euro").

  • Consequences, i.e. the action to perform if a condition comes true (for example, "display a warning message").

A rule is then simply a combination of conditions and consequences, for example: "if property A of object O1 reaches value X then set property B of object O2 to value Y."

A rule may have multiple conditions and multiple consequences. The logical rule between multiple conditions is always AND. If you need other logical operations (i.e. OR and NOT), these are not directly supported but can be easily programmed with scriptable rules (see below). Multiple conditions are evaluated in sequence, i.e. if the first condition becomes true, the second condition is evaluated, then the third condition, and so on. Once the final condition in the chain becomes true, then the rule triggers.

Multiple consequences in a rule are run at a non-deterministic random order. So if you set two consequences, one that subtracts a value of a property and another that adds a value to the same property, there is no guarantee that the subtraction takes place before the addition. It is good to bear in mind that while the arithmetic end result in this case is the same either way (addition and subtraction are commutative), setting a property may have an impact in some device that is controlled by the object and its property. Setting things in the wrong order may cause, for instance, overflows or malfunctions. If this is an issue, it is recommended to either use just single consequence per rule and chain two rules together or use scripted rules.

Also, a rule can include a negative condition: "if a given value is measured, don't do anything".

15.1.1. Creating a timer condition

Timer condition allows you to set the time to perform an action. You can set the timer to particular time and date or a sunrise or sunset event. A timer condition can be repeated daily or limited to specific days of the week. To create a timer condition:

  1. Go to Automation > Timer conditions. Click the "plus" icon and then the "gear" icon.

  2. Choose the timer type:

    • Clock — Sets the time for the action and (optionally) repeats it daily or on certain days of week.

    • Clock and calendar — Sets the time and date for the action, can't be repeated.

    • Sunrise/ sunset — Set the time to sunrise, sunset or noon based on the system location. Can be repeated daily.

  3. Fill in the fields for the chosen timer type.

    For all timer types, you can set a deviation, that means make the action happen within the specified time frame, for example, 600 seconds before or after sunset. This option is sometimes helpful if you don't want the rule to be triggered always at the same time.

  4. Save the timer condition.

To complete the automation, you need to add a consequence and define a rule.

Important

Sunrise and sunset calculation rely in the position information of your system. Define in in System settings for the correct calculation of this timer.

15.1.2. Creating a property condition

Property condition lets you create rules that are triggered when an object property takes a certain value. For example, if you need to turn on the heating when the room temperature drops below certain point, set the temperature threshold in the condition.

To create a condition:

  1. Go to Automation > Property conditions. Click the plus icon and then the gear icon.

  2. Fill in the fields:

    Condition name — Can be anything as long as it is unique.

    Target object — The sensor or other unit connected to the source device you want to monitor.

    Property to monitor — The property to track.

    Value limit — The property value which should trigger the consequence.

    Condition type — The type of event that makes the condition valid. For example, "value is greater than <the value threshold>".

    React to changes only — Whether the condition should be valid only when the tracked property value changes (as opposed to triggering the condition every time the value is updated, even if it has the same value as before).

  3. Save the property condition.

To complete the automation, you need to add a consequence and define a rule.

15.1.3. Creating a tariff condition

Tariff conditions are conditions that react to the prices of object properties. They can be used to automatically perform actions at the best price available. For example, you can make a rule to charge your vehicle at the moment when the electricity price is the lowest. Rules driven by tariffs are similar to this example: "When the electricity price is below 0.14 euro/kWh, start the charger. When the price is above 0.2 euro/kWh, stop the charger".

A tariff condition is triggered i.e. sends a signal that some consequence should happen when the targeted price is evaluated to be ove or under a given price. Prices have two limits: low and high. Therefore the evaluation of a rule can arrive in three states: below or at the low limit, between the low and high limit, or over or at the high limit. When under low limit, the tariff condition can send a low signal and above the high limit it can send a high signal when triggered. Nothing is sent when between the limits. Whether a signal is sent when the limits are met depends on the type of tariff condition. More about that below.

A tariff condition contains a price or the link to the price list that defines the price. If needed, you can add several price lists, for example, electricity prices for time-of-day, plus the distribution price, plus taxes. All these can be entered in the tariff condition as price components. The tariff condition combines these components and calculates the end price on which the rule is based.

By default, tariff-based rules are evaluated every hour. When evaluated, the total price affecting the rule is recalculated. The system then re-evaluates the rule and triggers the consequence if needed.

To create a tariff condition:

  1. Go to Automation > Tariff conditions. Click the "plus" icon to add a condition and then the "gear" icon to edit it.

  2. Fill in the condition name.

  3. Add a pricing component with the base price, markup and tax.

    • Base price — The basic price of using the resource. The base price can be: fixed (enter it in the field), variable (choose the price list) or downloaded from the specified URL (enter the URL).

    • Markup and tax — Additional charges. A markup can be entered either as a fixed amount in the currency, as a percentage, or both. A fixed markup is simply added to the price: if the price is 10 and the markup is 2, the resulting price is 10+2 = 12. A percentage markup is multiplication. If the price is 10 and the percent is 10, then the resulting price is 10*(1 + 10/100) = 11. A tax is handled similarly as a multiplication with the tax percent. In case several additional charges are entered, they are added in the order fixed markup > percent markup > tax. So if the price is 10, fixed markup 2, percent markup 10%, and tax 20%, then the resulting price is (10 + 2)*(1 + 10/100)*(1 + 20/100) = 15.84.

  4. Enter the tariff thresholds, Cheap/ low limit and Expensive/ high limit. The see below how these limits affect the way the rule is triggered. The limits can be set:

    • As a percentage from the average day price (for example, an interval of 10% below and 5% above the average day price).

      This option is good if you want the rule to work at least once a day, choosing the optimal price.

    • As a fixed price level (for example, from 4 to 8 euro).

      This option is stricter, as it means that you want the rule to work only at the specified price. If there's no such price during the day (from 00:00 to 24:00), the rule is not triggered at all.

  5. Save the tariff condition.

To complete the automation, you need to add a consequence and define a rule.

When you create the tariff condition, note that you have a choice between different types of controls. This choice affects when low and high signals are sent by the condition. The options are:

  • Start when below low limit, stop when above high limit — When triggered, this type of condition will send a false/off signal at every evaluation when the price is below lower than low limit, and a true/on signal at every evaluation when the price is above high limit. This option would work in the example with charging the vehicle in the intervals when the electricity price is acceptable. "Consequence 1" would then turn on the charger at cheap energy, and "consequence 2" would off at high energy.

  • Start just once when below low limit — This condition type will send a false/off signal on the first time when the price goes below the low limit. Later evaluations have no effect and no further signals are sent. This option would work if you need to perform some action just once at the moment when the price is good enough. For example, you can use it to buy a train ticket if it costs less than 20 euro.

  • Start once per day when below low limit — This condition type will send a false/off signal on the first time each day when the price goes below the low limit. Later evaluations on that same date have no effect and no further signals are sent. However a signal will be sent on the next day the first time the price is below the limit.

  • Always start when below low limit — This condition type will send a false/off signal at every evaluation when the price is below or at lower limit. Nothing is done at above the lower limit. By default, the prices are evaluated every hour.

  • Always stop when above high limit — This condition type will send a true/on signal at every evaluation when the price is above or at higher limit. Nothing is done at below the higher limit.

15.1.4. Creating a consequence

Consequences are actions that take place once the condition is fulfilled. To define a consequence:

  1. Go to Automation > Consequences. Click the plus icon and then the gear icon.

  2. Fill in the fields:

    Consequence name — Can be anything as long as it is unique.

    Target object — A connected unit that should react if the condition is valid.

    Action to perform — An action that should happen if the condition is valid:

    • Set controller on/off — Turn the controller type object on or off.

    • Set controller to value — Change the controller_property value of the controller type object.

    • Run an action — Perform an action programmed in Asema E application (you need to use Asema E as a gateway). Actions in Asema E enable you to control multiple units at once.

    • Display message — Display message on the screen.

    • Add, subtract, multiply, divide the property value.

    • Send an email — Send an email to the specified email address. The email template is set up in the System > Email section.

  3. Save the consequence.

15.1.5. Setting up and testing rules

To make a rule, put together conditions and consequences you created:

  1. Go to Automation > Rules and click Add new standard rule.

  2. Fill in the fields:

    • Name — The rule name.

    • Triggering conditions — Conditions that trigger the consequence actions.

    • Blocking conditions — Conditions that block the implementation of the rule even if the triggering condition takes place.

    • Consequence — Action to implement if the triggering condition takes place. Choose the consequence from the list.

    • Reacts when — Connection between the condition and consequence. In most cases, the rule assumes that the consequence should be implemented when the condition is true (the "Condition is true/start" option). However, if you are setting up a rule based on the tariff condition and two consequences (such as, "if the electricity price is low, turn the charger on, if the price is high, turn the charger off")(such as, "if the battery is low, turn the charger on, if the battery is full, turn the charger off"), add the consequences and specify when each one of them is used ("Condition is true/start" and "Condition is false/stop").

To test how the rule works, go to Automation > Rule tester. Change the condition values. When the consequence is triggered, you will see the message "Triggered rule <rule name>" at the top right of the screen.

15.2. Programming rules with JavaScript

15.2.1. Scriptable rules

Scriptable rules are rules written on JavaScript to perform custom analytics of events that take place in the Asema IoT system. The JavaScript is wrapped inside tags that make it valid QML and therefore capable of receiving and sending events to other objects through the internal JavaScript engine of an Asema IoT system. As the wrapper of the script is QML, you can also add QML elements useful for such programming such as Timers.

A scripted rule can perform both the condition part and the consequence in the JavaScript itself. This way the rule is a self-contained routine inside the rule engine and does not interact with anything else. Alternatively, the JavaScript section is just the conditional part of the rule. It is quite common that the evaluation of rule conditions requires more logic while the actual consequence is simple. For instance, turning on an AC may require a careful analysis of several variables such as temperature, humidity and time of day but the actual action to take is just turning on the device. This is why the script can just emit a signal then it triggers and the action can be linked to it as a standard consequence.

A JavaScript rule must begin with the import statement import RuleEngine 1.0 that imports the necessary hooks to the JavaScript engine. The rest of the rule must then be wrapped inside a RuleScript element. Please see sample code below.

Inside the rule there are two mandatory elements:

  • The signal result.

  • The function init().

result is the signal emitted once the rule triggers, i.e. wants to signal the engine that now the system should react to something. init() is a method guaranteed to be called by the rule engine once the rule has completed loading into the engine. It should contain all the initialization routines and work as the startup routine that actually runs the logic you have programmed.

Note that the rule engine does not call any other functions than init() at the very beginning when the rule is loaded into memory. Specifically: there is no method called by the engine when it wants the rule to be evaluated. Instead, the rest of the rule logic must work on events that you receive from objects. You need to program the rule so that the init() loads the objects you are interested in and then the rule connects to events such as measurableValueChanged of the object. This way your rule will react to changes in objects and their states immediately when events take place. Instead of relying on some method to be called at some interval, the rule will now be able to react in real-time to any change in objects that may take place.

To load objects during init, you need to find them. This is done using find methods of the objectManager (which is a part of the rule engine), including findObjectsByType and findObjectsByName. These operations are asynchronous. Before you call a find method, you must therefore define a callback which is called once the load completes. Once loaded, the objects are stored into a property of the context of your rule from where the objects can be fetched. The default context context is always available for this purpose. For instance, the call objectManager.findObjectsByType(context, "myAppliances", CoreObject.ApplianceObject); will use the objectManager to find all objects of the CoreObject.Appliance type and then store them to a property of context called myAppliances.

Note

The objectManager is exactly the same component that is used when programming custom applications, such as screenlets. For more details on how to use the objectManager, including programming syntax and the API, please refer to the application programming section of the Asema IoT Central user manual.See 12, Applications

Once you have a list of objects from objectManager, they can be connected to the rule logic. For example, context.objects.myAppliances.list[0].stateChanged.connect(applianceStateChanged) will take the first object in myAppliances and connect the stateChanged event into the function called applianceStateChanged.

applianceStateChanged should then contain the actual rule logic, i.e. what should be done when the state of that particular appliance changes. The event could, for instance, start a timer or a measurement or test what the state is now and then simply signal that the rule just triggered.

15.2.2. Writing a rule script

Below is an example rule which loads a set of appliances and sensors into the rule. Appliance state changes cause no real effect, they just log messages into the system log. Changes in sensor values are on the other hand compared to a threshold and if that is exceeded, the rule triggers.

import RuleEngine 1.0

RuleScript {
    id: myTestRule

    signal result

    function init() {
        console.log("MyTestRule is initing");

        myTimer.running = true;

        console.log("Example: Load the objects and connect to an object")
        context.objectsReady.connect(connectToAppliance);

        console.log("Example: Find all appliances")
        objectManager.findObjectsByType(context, "myAppliances", CoreObject.ApplianceObject);

        console.log("Example: Find a particular appliance by name")
        objectManager.findObjectsByName(context, "myAirQuality", "White air");

        return "init OK";
    }

    function timerTick() {
        console.log("Tic! Toc! The timer just ticked.");
    }

    function connectToAppliance(property) {
        console.log("Property \"" + property + "\" is ready.");
                        
        if (property == "myAppliances") {
            console.log("A total of " + context.objects.myAppliances.list.length + " items found");
            console.log("The first object is called " + context.objects.myAppliances.list[0].name);
            console.log("Example: Connect to a state change of appliance.");
            context.objects.myAppliances.list[0].stateChanged.connect(applianceStateChanged);
        } else if (property == "myAirQuality") {
            console.log(context.objects.myAirQuality.list.length + " items found with given name.");
            context.objects.myAirQuality.list[0].measurableValueChanged.connect(airQualityChanged);
        }
    }

    function applianceStateChanged(state) {
        console.log("Appliance state changed to " + state);
    }

    function airQualityChanged(name, value) {
        console.log("Sensor value " + name + " changed to " + value);
        if (name == "temperature_celsius" && value*2 > 80) {
            console.log("Trigger the rule");
            myTestRule.trigger();
            console.log("Done");
        }
    }

    Timer {
        id: myTimer
        interval: 10000

        onTriggered: {
            timerTick();
        }
    }
}
    

Chapter 16. Forecasting and optimizing

Forecasting is the process of taking a set of historic values of some object property and mathematically trying to predict what the values may be in the future. Forecasting can be used in visualization of predicted values to simulate how some logic or pricing may behave once taken into use. Forecasting also serves as the basis of optimization.

Optimizing on the other hand is an automation procedure that takes a forecast and then based on the forecast tries to find an optimal pattern for the usage of an object.

Rule automation and optimization are very much related processes. Both can run automatically in the background, both use the same principles and methods, and both rely on the data recorded from objects. However, there are also significant differences. Instead of conditions and consequences, optimization processes use routines. The way these routines operate make the difference between these two methods of automation.

AspectRulesOptimization routines
CustomizationCan be programmed and assembled from various components and consequently be fully customized.Preprogrammed to the system. Optimization routines perform solely the task they were designed for. System administrators can choose a routine and parametrisize it but after that the rest happens fully on autopilot.
Condition values (current/ future)React to current values. A rule will trigger exactly at the point when a change in the condition is detected.Work on future values. An optimization routine will take a forecast and plan the moments it will perform an operation well beforehand.
Data usedUse local data. For a rule to trigger, the value that is evaluated by a condition must appear as a value of a local object (or be a local clock).Can use remote data. Optimization routines can connect to a remote system and ask for a timeseries of data or prices. The routine then uses this remotely obtained data for its calculations.
Using timersTimers are optional. Rules can use timers if a timer or tariff condition is added to the rule. Always use a timer to schedule the points at which it will do predictions and plan their actions.
Objects to use withCan currently only be used with shared objects.Can be applied to any object.

16.1. Forecasting

Forecasting can be used in Asema IoT Central when designing price components and price lists, and when using optimization routines. Note that with price lists the forecasting function is illustrative only: it is there to help predict what the prices may look like under given assumptions of future conditions. The actual prices are then calculated at the actual points in time as time passes. With optimization routines, on the other hand, the forecast is taken as a guideline for a plan and that plan will then drive automation.

To use forecasting in visualizing pricing designs, there is a button in the corresponding user interface for displaying the forecast. See instructions on designing pricing for further details. Optimization routines on the other hand will use the forecaster that has been set up to it automatically.

Asema IoT Central currently supports five different types of forecasters: copying, windowed, linear, polynomial, and random.

16.1.1. Copying forecaster

A copying forecaster assumes that the future is a mirror image of the past. It takes a copy of the past values, starting from present and going back in history until enough values are available for the future estimate. These are then copied as such to the future. The copy may be reversed, i.e. the values are in opposite order compared to the past. The copy length may also be set, limiting the number of values that are copied from the past. If the copy is not long enough, it is repeated until the forecast is full.

To illustrate, assume that the history of a property has values V1, V2, V3, V4 and V5 at times T1, T2, T3, T4 and T5. The current timestamp ("now") is T5. If the copy length is set to 3 and the forecast should go until T10, then the values that are copied are V3, V4 and V5. The resulting series of values would be the following timestamp-value pairs: (T1, V1), (T2, V2), (T3, V3), (T4, V4), (T5, V5), (T6, V3), (T7, V4), (T8, V5), (T9, V3), (T10, V4).

Further, if reverse is applied, the values copied are still V3, V4 and V5 but they are copied in reverse order. The resulting series of values is then: (T1, V1), (T2, V2), (T3, V3), (T4, V4), (T5, V5), (T6, V5), (T7, V4), (T8, V3), (T9, V5), (T10, V4).

16.1.2. Windowed forecaster

The windowed forecaster is similar to the copying forecaster but instead of copying values from the current moment backwards, a window that represents a copyable region is given as parameter.

To illustrate, assume again that the history of a property has timestamp-value pairs (T1, V1), (T2, V2), (T3, V3), (T4, V4), (T5, V5). The window is given as T2-T4. The values that are copied are therefore V2, V3 and V4. The resulting series of values would be the following timestamp-value pairs: (T1, V1), (T2, V2), (T3, V3), (T4, V4), (T5, V5), (T6, V2), (T7, V3), (T8, V4), (T9, V2), (T10, V3).

16.1.3. Linear forecaster

The linear forecaster uses a linear regression model to fit a line to the past values that best represents the change in values. It then extracts the coefficients of this line and uses them to calculate the future values.

16.1.4. Polynomial forecaster

The polynomial forecaster is a generalization of the linear forecaster that fits a curve of the degree of N that best matches the historic values (the linear forecaster is actually a special case of the polynomial forecaster with degree N = 1). The desired degree is given as a parameter to the forecaster.

16.1.5. Random forecaster

A random forecaster generates, as one would expect, just random values. In this respect it has no prediction power but may come in handy for generating a simulation of events that produce seemingly random data. The range of random values can be inputted as a parameter. Additionally, you may define that the random pattern is a walk i.e. the curve is based on random amount of change (delta) instead of a completely random output.

16.2. Optimization

Optimization of an object property is done under the Sharing setup. Optimization is always done on the subscriber side. Once you subscribe to an object, under Sharing > Monitor and manage you will find currently obtained objects in a table with action icons for each. Click the "Automate" icon to proceed.

Next, select a property of the object you want to automate. At this point your system will contact the publisher and ask for updated details on the object pricing. Note that connection to the publisher must therefore be available.

Once the publisher is contacted, you'll be presented with a form that lets you start and stop the routine, make a single test run, and schedule the continuous running schedule.

To configure the routine to run, you need to select the type of automation routine you want to use (see below for the explanation on these). Once chosen, you get the routine-specific setup form. Two types of routines are currently supported: property optimization routines and tariff optimization routines.

16.2.1. Tariff optimization

A tariff optimization routine can be applied to objects where the publisher has either created a price list that is time- and tariff-based or is willing to send a timeseries of prices when requested. If a price list (specification) is received, the routine on the subscriber side will generate the corresponding price series. Otherwise the series sent by the publisher is used. If neither is available, the routine stops.

Similar to a tariff rule, the tariff optimization routine will try to seek prices that are either "low" or "high" and then set property values accordingly. The values of properties to be set in each case are configured to the optimizer. The property values will be set according to a time schedule that matches the moments when the price time series has those low or high values.

However, unlike a rule which only operates on the current calculated value, the optimization routine works on a series of prices and can therefore also find periods, not only instances of prices. So you can configure also how long a price needs to stay under or over a limit. Additionally, you can force the routine to always consider a given minimum amount of periods to be valid irrespective of whether they actually fulfill the low/high condition. So for example, you you require a minimum two periods to be valid low periods and no value is below the low limit, the routine will find the two lowest periods and use those.

16.2.2. Property optimization

A property optimization routine can be applied to objects where the publisher either created a pricelist that is property-dependent and also supplies those property values, or is willing to send the resulting price timeseries when requested.

The logic of the property optimization routine is very similar to that of a tariff optimization routine. It also will try to find the low and high points in the price curve and set property values accordingly. However, the property optimization routine takes the extra step of calculating prices based on the property values first.

Chapter 17. Simulating data

For various reasons such as testing an installation or running a demo, it would be beneficial to have the system automatically generate data and actions. There are several ways to achieve this, including building an external script that feeds commands through the JSON and Smart API's. These external scripts give full flexibility in designing the type of data and frequency it is fed into the system.

But Asema IoT Central also includes an in-build simulation module that starts automatically and generates values with a given pattern and then feeds them in. This simulation module is the easiest way to do simulation as it requires no programming. It is also reliable as only one component is involved and it starts automatically at system startup.

To use simulation, you add simulation parameters into the schema of the object. A special section simulate will contain the necessary parameters. Let's take a look at an example:

{
    "attrs": [
        {
            "property": "weight",
            "label": "Weight",
            "quantity": "http://data.nasa.gov/qudt/owl/quantity#Weight",
            "unitLabel": "kg",
            "simulate": {
                "method": "sine",
                "action": "set",
                "minValue": 10,
                "maxValue": 50,
                "frequency": 2
            }
        }
    ]
}
       

As you can see from the example, the simulate section is property specific. You can define a separate simulation for each property of each object. The simulation takes five parameters:

  1. method: this is the method with which data is generated. Allowed value are "sine", "square" and "random". Sine will create data using a sine curve, square results in a square wave, and random is just random data.
  2. action: what action to take when the value is fed into the object. Two options are available: "set" and "record". Set will use the set interface which causes full simulated action to take place, including invoking any hardware driver connections. Set is the option to choose when you actually want to simulate real automation input instead of just generating data. Record will bypass the driver routines and just store a value into the database. This is the best option if you are not interested in control automation but just need some simulated data.
  3. minValue: minimum value to be generated.
  4. maxValue: maximum value to be generated.
  5. frequency: the frequency of running the simulation in ticks. Each tick is 10 seconds so a value of 1 would run the simulation every ten seconds while a value of 6 would run it every minute.

Important

Note how the frequency is defined. These are ticks, not seconds. Currently there is no way to run the simulation faster than once per 10 seconds. For a faster simulation, use an external script or a server side script with a timer.

Once you have defined a simulation section, the object is added into the simulation engine and starts to run according to the schedule set by the ticks.

Chapter 18. Automatically cleaning up databasee values

Depending on the type of database you have and the need to store data, it may sometimes be useful to clean up old data from the database and just retain the new data. If your application only uses data from the past day, there may be no proper reason to keep an old log of values that unnecessarily takes disk space.

Asema IoT Central has an automatic cleanup engine which you can activate for each property. The cleanup routine is initiated by including a special cleanup section into the schema of the object. Let's take a look at an example:

{
    "attrs": [
        {
            "property": "weight",
            "label": "Weight",
            "cleanup": {
                "frequency": "hourly",
                "retainSeconds": 500
            }
        }
    ]
}
    

The example above sets up a cleanup routine that runs every hour and wipes out data of the property weight, retaining any values newer than 500 seconds.

cleanup takes the following parameters:

  1. frequency: how often the cleanup is run. Allowed value are "hourly", "daily" and "weekly". Note that this schedule applies to the specific property only. Consequenty, you could have an object where some properties are cleaned up hourly, some dailym and some weekly.
  2. retainSeconds: how much data is retained at clean. A value of zero wipes out all past data of the property whenever cleanup is run.

Note

The frequency of cleanup is calculated from system startup. If the system was started at 20 minutes past an hour, then cleanup routines are checked every 20 minutes past an even hour. Daily cleanups are run when the hour of checkup matches 3 a.m. Weekly cleanups are run on Sunday mornings 2 a.m.

Chapter 19. Users and access rights

In Asema IoT, access rights are defined with user groups and object zones. A user group is,as the name implies, a group of users. An object zone on the other hand is a group of objects. Theintersection of these two gives rights to operate an object.

Take an example: we have campus of several buildings. Each building has several remotely controlled relays. They are managed by two building managers that are assigned to a particular building. To give access to the relays of a particular building to a particular person, access rights would be set as follows: each building is a zone, so the relays of building A would belong to Zone A. The personnel belongs to groups, say Building A Managers, Building B Managers, and so on. Now, to grant access to the relays in building A to its managers, the access control would say "grant rights to objects of Zone A to the user group Building A Managers".

19.1. Add users

To add a user, go to System > Users > Users menu and click Add new. Fill in the fields, assign a groupto the user, then click Save.

Note

The user won't be able to change the password you provided unless they belong to the group that has access to user management menu.

19.2. Manage groups

By default, Asema IoT features two user groups, "everyone" and "admin". You can add as many additional groups as needed. Note that the scope of features associated with the admin group cannot be customized. This is to ensure that admins do not accidentally lose their ability to configure the system. The system requires that there always is at least one admin user.

You can create new groups and edit the list of features available to each group.

To create a group, click Add new, enter the group name, choose the features that should be availabe to the group and click Save.

To edit the list of features a group has access to, go to the System > Users > Groups menu, choose agroup and tick or untick the features, such as "Edit objects", "Edit content" and so on.

19.3. Restore the admin user password

If the admin password of the system was lost, it can be reset. To reset the admin password, you need to have access to the server where Asema IoT Central is running. To restore access:

  1. Quit/ stop Asema IoT.

  2. Start the program with the -P flag and with the new password as the argument. E.g. open the command line and enter the command:

    asema_iot_central.sh -P myNewAdminPassword

    Note

    It is not possible to recover a lost admin password from Asema IoT web interface. To change a lost admin password, you need to have admin/supervisor access to the actual computer that runs Asema IoT and use command line there.

Chapter 20. Managing and monitoring the system

20.1. Monitoring system availability

Many automated service monitoring systems require some basic response from a web service to check that it is on and running well. Asema IoT supports similar functionality, both in simple and more advanced form. For a very straightforward approach you could set up a simple web page on Asema IoT Central you poll or check that the logic page is available. However, there are better methods to achieve the same, either requiring less bandwidth or providing more monitoring data.

Asema IoT Central offers four alive polling and reporting methods for testing the availability of the service with simple HTTP GET request to an URL. Two of these return values fully in plaintext (suitable for e.g. network management tools) and two return a value with HTML headers (suitable for operating over an HTTP proxy for instance. The methods and their return values are

  • /alive. Return format text with HTTP headers. Responds with a simple "OK" if the system is online.
  • /tunnel_alive. Return format text with HTTP headers. Responds with a simple "OK" if the system is online and capable of communicating over CloudRoute VPN. This method is a direct extension to the /alive method with the added VPN check.
  • /version. Return format pure plaintext. Returns info of the system, including version number, system identifier and system name. Suitable for basic introspection and determination of system capabilities. Often the most lightweight polling method in case HTTP is not needed.
  • /poll. Return format pure plaintext. Returns system identifier, system time and uptime. Time values are supplied as seconds from epoch. Suitable for e.g. network monitoring tools as the timestamps progress continuously and make it easy to display not only if the system is up but also how well the system stays up.

20.2. Monitoring system health

Monitoring system health is an essential part of managing an IoT system. While the basic polling and availability methods described in the previous chapter give info on how the service itself is doing, a health report is a thorough analysis of the connections, connected devices, and the system components your installation has.

To obtain a report of system healt, call an Asema IoT system with the uri /health using HTTP GET. The call will return a JSON document which will detail various parts of the system, including the system time, available memory and disk space, available anetwork connections, software version numbers, and the details of hardware connections the IoT objects in the system have.

Chapter 21. Vocabulary and concepts

21.1. Objects

Every device, API or other controllable or measurable target in the Asema IoT Central is an object. Objects can be defined in different ways depending on their nature and source, but they are all available through one uniform API.

21.2. Pools

Gateways are devices that handle the traffic of other devices that cannot connect to Asema IoT Central directly. A common use for a gateway is to collect data from small wireless sensors. These sensors often do not support IP traffic directly. Instead, their values are read by the gateway and then relayed to the final destination by the gateway.

21.3. Gateways

Gateways are devices that handle the traffic of other devices that cannot connect to Asema IoT Central directly. A common use for a gateway is to collect data from small wireless sensors. These sensors often do not support IP traffic directly. Instead, their values are read by the gateway and then relayed to the final destination by the gateway.

Currently Asema IoT Central supports the Asema IoT Edge and Asema E gateways natively. The gateways can be automatically scanned from a network and every sensor that is handled by the gateway automatically becomes and object on the IoT Central.

21.4. Feeding data

In data feeding the Asema IoT Central acts as a server and an external device is a client that accesses Asema IoT Central APIs to feed data in.

To use data feeding, you must add a new Feed object from the Server API setting of Asema IoT Central. Here you can set the path of the API for the client device to use and the parsers for the payload that comes in.

21.5. Fetching data

In data fetching Asema IoT Central acts as a client which calls some API of an external server to fetch data. Fetching can happen automatically at set intervals or on demand when the object that defines the client is being polled for values.

To use data fetching, you need to device a new Client object at the Network clients setting of Asema IoT Central. Here you set the URL of the server to access as well as the parameters and payload to supply in the call and the instructions on how to parse the response.

21.6. Logging data

Data that is fetched or fed into Asema IoT Central is automatically signaled to various listeners such as the rule engine and the visuals. If you want to write this data to a permanent storage, activate database logging in the object list of Asema IoT Central. Once active, each change in the values of the object will be written to the measurements table of the database.

21.7. Visualizing data

Data visualization is one of the primary objectives of most IoT applications. Asema IoT Central offers powerful visualization tools for data either in 3D accelerated native GUI applications or in HTML5 browser environments.

Simple data graphs are directly available in the web admin interface of Asema IoT Central and in the Control Dashboard of the Asema IoT Central GUI. For programming your own custom visualizations, please refer to the Application Note on the topic.

21.8. Controlling objects

Every object in the Asema IoT Central that is defined as a controller can be remote controlled. Asema IoT Central offers multiple methods for creating a control application:

  • You can create visually stunning native GUI dashboards that contain buttons, sliders and various other controls for the objects.

  • The control GUIs can be embedded inside the Asema IoT Dashboard mobile app.

  • You can program a browser interface that allows users to remotely control objects with a web browser.

  • Controls can be programmed into the Asema IoT Central rule engine for automatic triggering of actions when some condition takes place.

  • The object API of Asema IoT Central lets other programs remotely control items either with standard JSON or with semantic commands.

  • Objects can be controlled directly from the admin interface of Asema IoT Central.

21.9. Rules and automation

The rule engine of Asema IoT Central can be used to create automated actions that trigger when the state of various objects change. This lets you link activities happening even in distant locations to specific consequences in totally different places, fully customizable by your configuration.

The standard feature of the engine comprises logical boolean rules called conditions that can be grouped to form one combined condition which triggers once all subconditions match. For instance you could say that a condition for a rule is that the temperature of the room must exceed a certain level while the humidity must be less than some other level.

The condition is then linked to a consequence which tells what will happen once the condition is triggered. As with conditions, consequences can be combined so that when one condition triggers, multiple consequences occur.

In case standard rules are not powerful for the needs of your automation topic, the rule engine also supports custom programming. A fully custom logic can be programmed with JavaScript using the embedded editor. In the custom rules you have all the capabilities of JavaScript available, including looping, logical conditions, mathematical conversions, and timers.

21.10. Content management

Asema IoT Central embeds an article based content management system (CMS). The purpose of the CMS is to provide tools for adding human input such as news, announcements and similar into the visuals. This way when Asema IoT Central is used to display data in a public location such as a lobby, the same screen can also be used as a bulletin board.

The CMS editing functionality is available in the Content section of Asema IoT Central browser interface. To display these announcements, the main GUI of Asema IoT Central must be turned into CMS view.

21.11. Tunneling and CloudRouting

Usually computers that run server software, such as Asema IoT Central, need a public IP address for other computers to access it. Asema IoT Central however uses a novel Virtual Private Networking (VPN) technology, reverse SSL tunneling, to create connections that can be used through firewalls to offer server capabilities to computers that do not have a public address.

The VPN is created automatically between devices and computers that belong to the same group (see 5.16, “Memberships”) and have the tunneling feature switched on. To turn on tunneling, go to System > Settings.

Each member in the group is assigned a unique CloudRoute address, which makes it possible to route the traffic between two computers in different local networks even when they happen to have exactly the same IP numbers.

21.12. Access control

You can secure Asema IoT Central from unauthorized access by creating access control credentials and assigning them to the API (see 5.15, “Credentials”). Depending on the authentication type you choose, the clients will be required to enter those credentials in the header or URL of the call to gain access to your data.

Likewise, other systems may require credentials to access them. Similarly you can create client side username and password pairs which will be used by Client objects when they access an external server.

Chapter 22. IoT network protocols

22.1. HTTP

HTTP, the HyperText Transport Protocol, is the workhorse of the World Wide Web and most likely the most used application protocol on the internet. HTTP is a straightforward message protocol that usesd a text format header, separated from the payload with a separator character. The payload itself can take many forms, depending on the application from plaintext to HTML, JSON and MIME encoded binary.

In IoT Applications HTTP is often used to carry JSON, JavaScript Object Notation, which, as the name implies, are easy to trnasform into objects in various languages, including JavaScript.

The transmitted JSON can basically be completely proprietary and defined by the application of follow certain standard notations such as JSON-RPC used in Remote Procedure Calls or JSON-LD, the linked data variant of JSON.

22.2. CoAP

CoAP, The Constrained Application Protocol, is a lightweight protocol designed as a replacement for HTTP in small embedded devices. It is a binary protocol that uses the minimal amount of bytes both in the header and in payload in order to squeeze itself into the limited package sizes sent especially by battery operated wireless sensors.

Similar to HTTP, the message is divided into header data (encoded in CoAP as "options") and the actual payload. Unlike in HTTP, the options are in binary format, not text. The payload can be anything, although in most applications it is also in some way binary encoded.

Unlike HTTP which uses TCP, CoAP uses UDP as its carrier protocol. This removes the retransmit capabilities thus reducing reliability but on the other hand reduces battery strain and bandwidth causd by TCP retransmits. Messages can be sent in pure "fire-and-forget" style though usually the messages are tracked with CoAP tokens which act as message identifiers. The recipient checks whether a message with a given token has been acknowledged and if not, retransmits.

CoAP core implementation only supports messages that fit a single UDP packet, limiting the size of data to the UPD packet size a device can transmit. An extension called blocked mode can also optionally be supported. In this mode the data is divided into several blocks which are then sent in individual UPD packages.

22.3. MQTT

MQTT, the Message Queuing Transport, is a messaging protocol especially suited for applications which need asynchronous messaging and reliable and fast delivery of short messages from one sender to multiple recipients.

MQTT uses a broker architecture where one server acts as a broker and other nodes connect to it as publishers and subscribers. MQTT defines the concept of a topic, a freely defined string that identifies a given type of messages. Anyone who has subscribed to a particular topic at the broker will receive all the messages of that topic once someone publishes such a message. For instance there could be several thousand subscribers interested in knowing the result of some calculation. They all subscribe to the topic at some point prior to the calculation taking place and leave a listening socket open to the broker. The node that makes the calculation opens one connection to the broker to make the announcement and the broker uses the open connections to send the results.

As only one announcement is needed, this reduces the communication burden of the calculating party. Further because everyone connects to the broker as clients, all connections take place outwards from any network, making it usually possible to communicate in two directions through a firewall.

Colophon

<bookinfo>Asema Electronics Ltd<copyright><year>2011-2019</year></copyright><legalnotice>

No part of this publication may be reproduced, published, stored in an electronic database, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, for any purpose, without the prior written permission from Asema Electronics Ltd.

Asema E is a registered trademark of Asema Electronics Ltd.

</legalnotice>
</bookinfo>