The local deployment option if for install the OSI4IOT plataform in a single machine. Select the local deployment option. The following options will be available

************************************************
**   WELCOME TO OSI4IOT PLATFORM CLI v1.1.0  **
************************************************

? Select the place of deployment of the platform: Local deployment

Init platform
Run platform
Clear screen
List organizations
Create organization
Update organization
Remove organization
Recover nodered instances
List nodes
Add nodes
Remove node
Update domain certs
Platform status
Stop platform
Delete platform
Exit

To initialize the platform for first time, use

Init platform

Several fields will be then prompt to be input. If enter pressed, the option between parenthesis will be inserted instead.

************************************************
**   WELCOME TO OSI4IOT PLATFORM CLI v1.1.0  **
************************************************

? Select the place of deployment of the platform: Local deployment

? Choose one of the following options:  Init platform
? Platform name: OSI-DEMO
? Domain name: iot_fiber4yards_demo.org
? Platform motivational phrase: Open source integration for internet of things
? Platform admin first name: admin_f4y
? Platform admin last name: demo
? Platform admin user name: admin_f4y_demo
? Platform admin email: admin_f4y_demo@gmail.com
? Platform admin password: **************
? Retype platform admin password: **************
? Min longitude of the geographical zone of the platform: -10.56884765625
? Max longitude of the geographical zone of the platform: 1.42822265625
? Min latitude of the geographical zone of the platform: 35.55010533588552
? Max latitude of the geographical zone of the platform: 44.134913443750726
? Default time zone: Europe/Madrid
? Main organization name: My main org
? Main organization acronym: MYORG
? Main organization address: fake street, fake number
? Main organization city: fake city
? Main organization zip code: 00000
? Main organization state/province: fake province
? Main organization country: Spain
? Telegram boottoken for main organization default group: 5342540378:AAHrJ4ABFiX54m6uf9RvxHxLRKeo0dGiHA0
? Telegram chat id for main organization default group: -694425020
? Telegram invitation link for main organization default group: https://t.me/+MgGprvw5SAozODq0
? Number of node-red instances in main org: 3
? Email account for platform notifications: admin_f4y_demo@gmail.com
? Email account password: **************
? S3 storage bucket name: osi-demo

A guideline for the local deployment can be found in .

Next, select the type of certificate for your domain SSL certification.

? Choose the type of domain ssl certs to be used: (Use arrow keys)
> No certs
Certs provided by an CA
Let's encrypt certs and AWS Route 53
AWS Certificate Manager

A guideline for the SSL certificates is found in .

If the certificates are correctly introduced, the platform should be initialized correctly. A similar image to this one should be obtained.

The on-premise cluster deployment option if for install the OSI4IOT plataform in a cluster of machines on-premise.

The AWS cluster deployment option if for install the OSI4IOT plataform in a cluster of machines on AWS.

The `OSI4IOT` platform is not limited to monitor different sensors and to provide an equivalent 3D digital twin of an asset. When considering the IOT technologies, large and distinct information can be gathered, post-processed and generated by different stakeholders. To control that the information is only accessible to the right person, the platform considers different levels of abstraction:

• Organizations
• Groups
• Devices
• Assets

Organizations are the most external level of hierarchy found in the platform. An Organization represents an stakeholder in the OSI4IOT ecosystem. A stakeholder can be either a cluster of organizations or a unique organization. The contents of a stakeholder is not limitted to the partial or complete content of the same organization, but partial or complete contents of different organizations.

Only the platform admin has access to all the information stored in each stakeholder, however, different organizations can share with each other partial information through a organization-to-organization message protocol.

The simplest stakeholder would be to harbor the partial or complete contents of a unique organization. In this case the stakeholder could be just a company and the immediate inner level of hierarchy, the group level, could be departments of the company.

When the structure of the stakeholder is not straightforward, for example in the case of a cluster of organizations harboring partial or complete content of the different organizations.

This type of structure could be useful in the case of a single organization that not only subdivides its structure into departments at the group level, but also when it has to manage data coming from different sources such as partner organizations, customers and suppliers integrated into the platform.

The most complex infrastructure that can be deployed and integrated in the OSI4IOT platform would be the case of different organizations working together (cluster) and wanting to digitalize and interconnect their processes and information generated. In this case the stakeholder level would be the cluster and the group level would be comprised from organization's departments to partners.

Inside the platform, the organizations or stakeholders are geolocated and displayed in the map with all their content information (groups, assets and sensors).

In the map, first you can see a general view with all the organizations included in the platform.

If one of the leaflets are selected, the view will focus on the building of the selected organization.

The next level of hierarchy is the group. This level offers the possibility to divide the data stored in the platform in different compartments. This way only members that are at the organizations level can access to all the groups, but a unique member of a specific group cannot access the information of another group.

Although a member of Group 1 would not have access to Group 2. There is the possibility to share information between groups using a group-to-group message protocol similar to the protocol between organizations.

Inside the platform, the groups are geolocated and displayed in the map inside the domain of their organization, the information that can be displayed are the devices and nodes of the group.

A device can have one or more industrial machines connected to it in order to control the production process. This machines or parts of a machine are represented by an abstraction called asset.

Inside an asset can have the following components:

• Sensors

  An asset can have multiple sensors to measure the relevant parameters that allow defining its status. Temperature, pressure, viscosity or accelerometer sensors are typically used in the manufacturing industry.

• Digital twins

  An asset can have one or several digital twins. A digital twin is a virtual model designed for accurately reflect the physical state of the asset. The function of the digital twin models are the following.

  • Asset state monitoring
  • Predictive maintenance
  • Alert system in case of incidents

  To implement a digital twin, machine learning models trained by mean of the data collected by the sensors, can be used. Other methodologies, such as the application of model order reduction to physically-based model are also available.

• Asset state

  The state of the asset at a given instant is defined by a set of parameters. These parameters are obtained from the data collected by the sensors and from some evolution model. It is important to store in a database the historical evolution of the asset state so that they can be used in the development of digital twins.

• Asset topics

  The communication protocols typically used in IOT technologies (MQTT, Apache Kafka and Apache Pulsar) use the term topic to refer to the text string used to filter the messages that a publisher sends to the receivers. It is necessary to store in database a list of the different topics used to send data related with the assets.

Once you understand the key points of the platform components, the hierarchy levels and what is the purpose of each level. The other missing part is how to manage the platform components. This is the purpose of the role managing system, which associates a role to certain levels.

If logged into the platform, the first thing that you will see is the role menu bar in the left. From bottom to top of the role menu bar we have:

• Super Admin: role associated generally to the people who are in charge of the platform and generally install it.
• Organizations Admin: role associated to the management of the organizations, creation of groups, etc.
• Groups Admin: role associated to the management of groups, creation of devices and assets.
• User: role associated with the management of the personal information of the corresponding user.

The hierarchy of roles is established as:

Super Admin > Organizations Admin > Groups Admin > User

The home button is just the viewer and it is available to all the roles. The descendent order implicates that the role below is of higher rank, for example a Super Admin can manage the same information as the Organizations Admin, but not otherwise.

The following picture illustrates the information that can be accessed by the different roles.

The home screen hosted in the the domain provided in the CLI offers 4 possibilities:

• Platform assistant:

  The core of the platform where the different users can access to all information stored in the platform. It gives access to the managing role menus.

• Dashboards

  Use this option to open Grafana application in another browser tab.

• Digital twin simulator

  This option is a simulator for the Digital Twin Models. This simulator allows to modify the parameters of the DTM in real time. With this, you can display the model in a device and control the simulation parameters from another one.

• Mobile sensors (Only Android devices)

  This option is used to demonstrate that the platform also integrates mobile technology. For example, it is possible to capture the accelerometers of an Android phone or even use machine learning models to label information from a picture taken by the phone.

The first thing that is needed is the access through the login screen. If you are the `Super Admin`, then you will login with the credentials introduced in the `CLI`, however if you are not the one who initialized the platform or have a lower rank assigned, then you will need to be invited by the `Super Admin`. This is easily done by means of adding a new user (you need an e-mail) in the `Global users` tab of the actions available to the `Super Admin`.

Click on the top right icon to login.

Then fill the form and submit.

Then you will be redirected to the Platform assistant app, where you will be able to see the different organizations in the map.

One of the type of information that can be visualized are dashboards, useful to desplay simple sensor data and with the option to send alerts through the notification system when a certain threshold is trespassed.

It can be accessed from the viewer by clicking the dashboard icon.

Then the dashboard is displayed. In this example the measurements of a temperature sensor.

The same result can be achieved from the Dashboards option in the home screen. A list of the different dashboards is shown, the access to the list depends on the account rank of the user, then select the appropiate dashboard.

The other type of information that can be displayed are the Digital Twin Models (DTM). They can be accessed when selecting a device, and by clicking the DTM icon (three boxes), the viewer will load a 3D digital twin.

Here you can control and monitor the sensor information, in this example, the level of water in a tank on top of a building structure. The rendering offers the possibility to show the current results in the format of a Finite Element Method mesh or in short FEM mesh. For example the distribution of stresses in the floor and at the current time to plot the deformation, in real scale or custom. The platform offers the possibility to lock the measurements and use the simulator to observe hypothetical scenarios. Sensors embedded in the digital twin can also be accessed by clicking the sensor in the 3D model.

It can also be the case that you may want to monitor an asset with the 3D view while simulating the model with an external device. This can be done by using the Digital Twin Simulator option in the home screen. You will see in real time the modifications introduced in the simulation.

Any 'DTM' requires a logic to analyze in real time the information coming from the sensors and decide whether to trigger an alert when something goes wrong. This task can be done with the help of Node-RED, an open source package that allows graphically to interconnect the data and manipulate it. You can either create custom boxes or use existing template boxes to design the flow diagram of the logic of your devices.

The Node-RED instances can be accessed by clicking into the Node-RED icon in the map.

The platform uses Mosquitto as the message broker. This message protocol uses a publish/subscribe model associated to a topic. Topics are the channels of information where a device can connect to publish data or subscribe to fetch information.

The platform implements a specific format to communicate through the MQTT protocol. Note that devices are associated to groups, and they send information through a topic. However, the format also takes into account the type of information that is sent in the topic. Therefore the format required to establish communication from a device to the platform is:

<topic type>/Group_<group hash>/Device_<device hash>/Topic_<topic hash>

Topic types:

• dev2pdb : Device to platform database.
• dev2pdb_wt : Device to platform database with timestamp.
• dev2pdb_ma : Device to platform database messages array.
• dev_sim_2dtm: Simulated device to DTM.
• dtm_as2pdb : DTM assets state to platform database.
• dtm_sim_as2dts: DTM simulated assets state to DTS.
• dtm_fmv2pdb: DTM fem modal value to platform database.
• dtm_sim_fmv2dts: DTM simulated fem modal value to DTS.

Besides complying with the format, the security of the platform ensures that only the roles that can manage devices are allowed to send or receive information through a topic. Therefore you need to connect through credentials to the platform prior to use a topic.

Not only users can use their credentials to send or receive information. There is the option that the device that publish and subscribes to the topic does itself. In that case, there is the option to download the SSL certificates, three certficates (CA,Client Certificate, Client Key). This method enables the device to send or fetch information without any account.

There is a more complete manual on how to communicate and use the MQTT protocol available in .