NAV Navbar

Basic concepts

What is Eugenio Platform?

Eugenio is a IoT end-to-end platform (hardware and software-as-a-service) created by Logicalis for simplifying the building of custom IoT solution.

The benefit of a platform is to provide commodity capabilities faster and cheaper while maintaining the ability to differentiate through customization. 

The Eugenio IoT Platform is the foundation for a custom IoT solution. The platform provides makers and developers with core IoT capabilities from which a custom IoT solution is produced to your specification with security, scale and reliability, from device and gateway, up to the cloud.

Eugenio’s reference architectures is based on three layers: Fog, On-Premise and Cloud.

Fog

The Eugenio Fog Computing layer is composed of the Intelligent Gateway (IG) and the Intelligent Sensor Device (ISD).

More than just simple data aggregation and communications enablers, the Eugenio Intelligent Gateway also allows software customization to meet advanced functionality such as connectivity integration, device control, firmware updates, analytics, and security.

The Intelligent Sensor Device provides a modular hardware that is a starting reference design to build a wide array of advanced customized IoT devices with individual hardware specifications.

The easy fog-to-cloud integration allows you to take full advantage of Eugenio resources to deliver compelling solutions quickly while reducing risk, cost, and development cycles.

On-Premise

The On-Premise is a optional complementary server-based layer that enables time-critical information analysis on site in situations where the Fog layer is not able to provide sufficient computational resources to meet the solution requirements.

Cloud

The Cloud layer is a cloud infrastructure which supports the elastic big data architecture of Eugenio and provides ready-made scalable capabilities for ingesting, processing, and storing device data for unlimited reliability and scale.

Eugenio Cloud layer simplifies managing device (Eugenio Fog or third-party devices) and enterprise system integration, anywhere, at any scale by providing the features and an extensibility model that enable device and back-end developers to build robust device management solutions.

Its open architecture provides a set of developer services that can be used individually or together in a standards-based and interoperable environment with support for multiple internet protocols, including HTTP and REST.

Infrastructure management is automated with a platform that is designed for high availability and dynamic scaling to match usage needs.

How do I start using Eugenio?

To use the Eugenio platform in the building of your IoT solutions, you must follow some initial procedures:

  1. Contact Logicalis to request the creation of your Organization
  2. Once your Organization is created, you can access the Eugenio with your email and password. If you don't have a email/password, request one to your Organization Admin.
  3. Access Eugenio Portal here and identify yourself with the email and password provided.

Eugenio APIs

To browse through Eugenio APIs, go to: Eugenio API Explorer.

The below sections discuss importants notes about how Eugenio does authentication and authorization.

Authentication and Authorization

Eugenio supports two ways to access APIs: using API Key and JWT. The developer should plan when and how to use one of these credentials methods. If both methods are provided, then Eugenio will honor API Key first.

The authorization is made through policies, where is possible to customize the access permissions to each API provided by Eugenio. To do this follow these steps below: 1. At Eugenio interface, access the Policies menu 2. Create a policy - Add permissions - Associate to users - Associate to applications

Usually we recommend the use of API Key when you are building an application. And JWT when you are exploring the Eugenio APIs.

API Key

To start using the APIs and building your solutions, you need to get an API Key. To do this, follow these steps below:

  1. At Eugenio interface, access the Applications menu
  2. Create an application
    • Be sure to select the correct organization
  3. After saving, the API Key will be created. Copy and save for use in all your API calls
    • To get easy the management, you can generate as many API Keys as needed.

With the API Key you are able to get access all Eugenio API. Example:

curl -H 'apikey: {generated_api_key}' \
  https://portal.stg.eugenio.io/api/v1/data

You should use API Key when there are a specific applications builded with Eugenio API and you must keep this application long runner.

JWT

When you access the Eugenio Portal using an provided login, all http interaction is using JWT (Json Web Token).

But JWT is not only used during web user interface sessions. A user could use JWT to get access to Eugenio API, as well using API keys.

To get a valid JWT to run some tests, run this command:

curl https://portal.stg.eugenio.io/api/v1/auth -d
'{
   "email": "eugenio@eugenio.io",
   "password": "PASSWORD",
   "tenant": "TENANT NAME"
 }'

The command result will have a property called 'access_token' this is the JWT. Example:

{
  "access_token": "string",
  ...
}

Then, to use the JWT, put it on HTTP header like this:

curl -X GET https://portal.stg.eugenio.io/api/v1/users \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Devices

Eugenio platform supports three types of devices:

The "hub" function implies that the communication protocol between the gateway and the IoT devices must provide the gateway with the ability to initiate a data exchange. And, in fact, that happens and the gateway has been the master in a master-slave communication with the devices, which occurs over an RS-485 wired network.

The second function, "bridge", implies that the gateway must have enough communication resources to connect to a cloud service. In our case, the gateway has Ethernet, Wi-Fi, Bluetooth and Cellular, through the MQTT and HTTP protocol.

Physical Installation

Logicalis Devices

There are two things to be attempt before power on the gateway:

Antennas

There are three types of antennas you can plug in:

You can check the correct set of each antenna in the image below.

Gateways antennas

After that, your gateway is ready to go online. On the gateway side there are two other sockets (ETH0 and ETH1), these are used for local settings in the gateway with network cable.

Using the ETH0 socket, simply connect the cable and start using the user interface on IP 192.168.1.1 in the browser. ETH1 is also enabled to get the same interface, but you must manually configure the IP address.

Gateways power and connection

The IG (Intelligent Gateway) provided by Logicalis has the automation process to register in broker from the moment you turn on and connect it to internet the first time.

You can verify if it's correctly registered by Eugenio Portal, in List of Devices section (Gateways tab). In case of success, the Gateway will be listed (even if it's disconnected).

List of gateways register test

Intelligent Sensor Devices (ISD)

You can see below the connection scheme of the sensors in both the device (when there are buses for each ISD that you want to connect) and also in other sensors (in case it is necessary to create a series connection scheme of the ISDs to the device).

Isd scheme

You can check if it's correctly registered either by Eugenio Portal, in ISDs tab.

List of isds register test

Device Connection and Message Exchange

To allow your device to connect to Eugenio, you must register it by following the steps below:

  1. Login to Eugenio GUI

  2. Create the device data schema (more information at Defining a Schema)

  3. Create the device (more information for generic or Eugenio devices are explained below at Register Device)

Create a new client certificate

Communication between devices and Eugenio is protected through the use of X.509 certificates.

You must use your own X.509 certificate. The following steps show an example of how to create a self signed X.509 certificate locally in Linux using a tool called openssl.

The below command generates a client certificate (cert.pem file) and a client key (key.pem file). Both file must be saved and will be used during the MQTT client connection:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj '/CN=localhost'
Option Description
-newkey rsa:4096 Generate a 4096 bit RSA key.
-keyout key.pem Save a key to the key.pem file.
-out cert.pem Save a certificate to the cert.pem file.
-nodes Do not protect the private key with a passphrase.
-days 365 The number of days to make a certificate valid for.
-subj '/CN=localhost' Use this option to suppress questions about the contents of the certificate. Replace localhost with your desired domain name.

The next step is to get the thumbprint from the cert.pem file. The following shows the thumbprint:

openssl x509 -in cert.pem -fingerprint -noout
Option Description
-fingerprint Print the certificate fingerprint
-noout No certificate output

Save the thumbprint, it will be used during the Eugenio Device creation.

Register Device

The next step in process of sending messages from device is to make the register with broker.

For generic devices, there are four steps to be follow to have the device created and registered:

For Eugenio devices, the requirements and commands are specified "Devices Management API".

When a Eugenio device was registed with success the JSON response's body from POST request is compose by a mqtt section wich has the follow components:

You will need these elements to connect the device to the Eugenio Cloud.

Device Connection to Eugenio

Real Device

MQTT Connection

This quick start guide will teaches you how to configure a MQTT client tool to connect and send MQTT messages to Eugenio. Furthermore how to query the data sent by devices.

Client configuration

The following examples shows how to setup a MQTT client:

import paho.mqtt.client as mqtt
import ssl

ca_cert = ''
device_cert = ''
device_key = ''
device_id = '<DEVICE ID>'
username = 'logicalis-eugeniostg-iothub.azure-devices.net/' + device_id + '/api-version=2017-06-30'
password = None

client = mqtt.Client(device_id, mqtt.MQTTv311)

client.username_pw_set(username, password)

client.tls_set(ca_certs=ca_cert, certfile=device_cert, keyfile=device_key, cert_reqs=ssl.CERT_REQUIRED, tls_version=ssl.PROTOCOL_TLSv1, ciphers=None)

client.tls_insecure_set(False)

Eugenio only supports X509 authentication over Secure MQTT connection (usually port 8883/tcp). So make sure that your MQTT Library supports it.

To connect using X509 you will need the following files:

There are three important points to know:

Client Connection

The following code show how to connect:


broker_mqtt_hostname = 'logicalis-eugeniostg-iothub.azure-devices.net'
broker_mqtt_port = 8883

client.connect(broker_mqtt_hostname, broker_mqtt_port)

The next step is to make the inital MQTT broker connection using the 'broker_mqtt_hostname' and 'broker_mqtt_port' got from device registration step.

Now, your device is connected and ready to publish messages and subscribe topics.

Simulated Device

Setup MQTT Client

  1. Download and install MQTT.fx (based on your OS version). You can download the latest MQTT.fx from here.

  2. Configure the connection profile:

    • Broker Address: type the host that you noted earlier (for example, logicalis-eugeniostg-iothub.azure-devices.net).
    • Broker Port: type the port that you noted earlier (for example, 8883). Make sure this port is open in your firewall.
    • Client ID: type the device ID that you created earlier in Eugenio (for example, mqttfx_device).
    • User name: type <host>/<device ID>/api-version=2017-06-30 (for example, logicalis-eugeniostg-iothub.azure-devices.net/mqttfx_device/api-version=2017-06-30)

    Mqtt connection 1

  3. On the SSL/TLS tab, make sure that the Enable SSL/TLS check box is selected. From the Protocol drop-down menu, choose TLSv1. Select Self signed certificates. Under Self signed certificates, choose the CA certificate you downloaded earlier during the device creation, and the client certificate and the client key you saved earlier during the client certificate creation, and select PEM Formatted.

    Mqtt connection 2

You do not need to do anything on the Proxy and Last Will and Testament tabs. At the bottom of the page, choose Apply and then OK.

Connecting the simulated device to the Eugenio platform

Follow these steps to connect the MQTT.fx client to the Eugenio platform and send messages.

From the drop-down menu at the top of the page, choose the connection profile you created earlier and click Connect to connect to the Eugenio platform.

Mqtt connection 3

Under the Publish tab, at the first field, enter the deviceToCloud topic that you noted earlier (for example, devices/mqttfx_device/messages/events/). In Payload, type the following JSON:

Please replace the 'timestamp' and 'int value' with your data.

{
  "schema": "mqttfx_schema",
  "payload": {
    "event_date": <timestamp>,
    "event_value": <int value>
  }
}

Make sure that the QoS 0 check box is selected and then choose Publish.

Mqtt connection 4

Under the Log tab, you can check if the message was sent successfully.

Message Exchange

Device to Cloud messages

There are two type of events that an device need to handle:

Sending events

The follow examples shows how to publish an event:

import json

topic = '<deviceToCloud parameter>'

message = {
    "schema": "my_device_door",
    "payload": {
        "ls": 30,
        "rs": 50
    }
}

client.publish(topic, json.dumps(message))

After the Eugenio device register using HTTP API, we got from JSON response body a parameter called 'deviceToCloud'. This parameter should be used as MQTT topic to publish messages from device to cloud.

To publish, you will need the topic (returned in device registration) and the message (remembering that must to follow the schema). You can see a example of a publish to the cloud.

Receiving commands

The following example show how to do topic subscription:


cloud_to_device_topic = '$iothub/methods/POST/#'

def on_connect(client, userdata, flags, rc):
    client.subscribe(cloud_to_device_topic)

Eugenio has the feature to send commands to connected devices. This is done using Cloud to Device messages.

The device should be prepared to subscribe to specific topic: $iothub/methods/POST/{method name}/?$rid={request id} where:

The body that the device receives is a JSON content. The device code must handle method name, e.g: calling a related method. And the 'request id' must be keeped to publish the response.

Sending commands replies

Once the device handled the operation, its time to reply using a status and message.

The device publish response messages to $iothub/methods/res/{status}/?$rid={request id}, where:

The payload message should be a valid JSON and the status could be any integer. E.g: 200 which indicate a success operation.

The following example how to reply commands:


def my_command(cmd = None):
    200, "{}"

def publish(message, status=200, rid=None, publish):
    direct_method_reply_topic = "$iothub/methods/res/{status}/?$rid={request id}"
    topic = direct_method_reply_topic.format(status=status, request_id=rid)
    publish(topic, message)

def on_message(client, userdata, msg):
    cmd = msg.topic.split('/')[3]
    rid = msg.topic.split('/')[4].split('=')[1]

    # call any method do process the command
    status, reply = my_command(cmd)

    publish(reply, status, rid, client.publish)

Cloud to Device messages

To send cloud commands to device, just use the Invoke API. The device must be prepared to handle the event received and response they.

From the application side, sending commands is just a call to http endpoint that handles all the communication between the cloud and device.

To send command events to Device, do:

curl -X POST https://https://portal.stg.eugenio.io/api/v1/things/{deviceId}/invoke \
  -H 'apikey: <api key>' \
  -H 'Content-Type: application/json' \
  -d \
'{
  "method": "string",
  "payload": "any",
  "timeout": "integer"
}'

After the device replied the request with command, the backend application receives a response that comprises:

{
    "status" : 200,
    "payload" : {...}
}

Both status and body are provided by the device and represents the command status and any reply from command.

Data

Eugenio lets you pull your data out to a external application through a RESTful API.

Defining a Schema

Data Consulting

Calling the Query API

Query API is implemented in the REST style. This means that you can call the Query API from a variety of development environments, and even from your browser. The correct syntax is as follows:

Substitute <APIKEY> and <SQL_ENCODED_STRING> with the right values.

curl -H 'apikey: {generated_api_key}' \
  https://portal.stg.eugenio.io/api/v1/data/query?sql=<SQL_ENCODED_STRING>

Eugenio suports the Impala SQL dialect. For more details, please refer to the Impala SQL Language Reference

An example of a valid query:

Please replace the <organization> and <schema> with your organization and schema names.

SELECT * FROM <organization>_sandbox.v_<schema> \
  ORDER BY created_at DESC LIMIT 10