Resources (Digital Twin)

icon

Introduction

In waylay, a resource is not strictly assigned to a device. Resource can be any entity you can think of, such as a device, a parking lot or a city.

How resources get created in Waylay? Every time data arrives, Waylay checks if a resource that is associated with that data already exists. If not, Waylay will create a new resource automatically.

Resource can also be created using REST interface, or simply in the UI, from the resources table view (see button Create new resource):

resources

resources

Resource concept is important in many different ways:

  • we can associate metadata with a resource
  • we can associate data with a resource
  • we can link sensors or actuators to the resource (in that case a resource can be seen as the address space, allowing the rule engine to route calls to all sensors for all running tasks)

Resource metadata - concept of a digital twin

In waylay, a resource meta model can handle two different concepts of a digital twin:

  • metrics configuration (to describe which data can be collected on this resource)
  • commands concept (to abstract actuations allowed on this resource)
  • sensors concept

Meta model supports hierarchical parent/child relations between resources. Resource inheritance (and rules execution) is achieved via the resource type concept, while the parent/child concept is only about relation (and navigation). This simplifies building custom UI applications, such as smart buildings, where buildings and floors can be used to group set of resources (e.g. building A, floor 2 etc.) using parent/child relation. See the diagram of the metamodel below:

Here is of the view of one particular resource, in this case a Sigfox device: resource

In the first tab, we see metadata for this device, some of which are inhereted from the resource type

Metrics

We can also see all metrics and data which is collected for this resource in Data tab. data

data

Since Waylay automatically stores payload data in time series database, we can see all data this way too (resources/$resource/$metric): data2

There is also a payload storage, which is kept for inspection, and by default, Waylay stores the last 100 messages for each resource: data3

Commands

Commands feature allows you to specify generic set of actuators for a resource, which at runtime get resolved to a specific actuator. For instance, this level of abstractions allows developers to model all lamps from different manufacturers with their capabilities such (turn off/on, dimming etc..) and then at meta level define different actuations for different resources. This enable much easier REST integrations with 3rd party apps. Example: When a command is sent to the broker for the resource and with command SayHi, the engine will check the commands property of the resource’s metadata and see if there is a command SayHi mapped to an actuator.

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_friendly_device",
    "commands" : [{
       "SayHi" : {
         "actuator" : {
            "name": "debugDialog",
            "version": "latest",
            "properties" : {
              "message": "Hello !"
            }
         }
       }
    }]
  }' "https://sandbox.waylay.io/api/resources"

If there is such a property and the mapped actuator could be found, the properties for the actuator are merged with the actual message sent to broker. Then all properties are checked for metadata properties templating and resolved to the actual metadata values. Finally the actuator is executed for the resource and the merged properties:

Send a SayHi command for resource testresource

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "name": "SayHi",
    "message": "Hello from this friendly resource"
  }' "https://data.waylay.io/resources/testresource/commands"

You can at any time check all commands sent to the resource by looking at the commands tab: commands_log

Sensors for resource

You can also specify set of sensors that are applicable for a given resource. Please note that there is no explicit action taken by waylay platform on this meta key, unlike for commands, where waylay platform resolves a particular actuator for a given command call. Idea behind this abstraction is to assist integrations where an architect of the digital twin can specify which sensors from waylay library are applicable for a given resource (or resource type). For instance, you may have one sensor per metric, or multiple sensors for a given metric, or one sensor that is using multiple metrics. When calling a REST interface for meta, UI can be dynamically built based on set of capabilities for a resource both for actuations (using commands) and also associate set of sensors, next to supported metrics.

Create a resource with events sensor (which represents GoogleCalendar sensor)

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_friendly_device",
    "sensors" : [
      {
        "name": "events",
        "sensor": {
          "name": "GoogleCalendarStreamSensor",
          "version": "0.1.5"
        }
      }
    ]
  }' "https://sandbox.waylay.io/api/resources"

The sensors property must be an array of objects. Each object must have a name property that describes the sensor along with a sensor property which is an object containing following properties:

Property Value
name Name of a sensor
version Exact version of the sensor or latest
properties Json object with default values for the properties of the sensor

Sensor properties in meta

[
  {
    "name": "<custom-name-for-sensor>",
    "sensor": {
      "name": "<sensor-name>",
      "version": "<sensor-version>",
      "properties": {
        "<some-sensor-property>": "<property-value>",
        "<another-sensor-property>": "<property-value>"
      }
    }
  }
]

Resource concept used for stream data routing

This is how you assign a resource to a sensor in the rule designer.

resources

The resource is a unique identifier of a ‘thing’. When a ‘thing’ pushes streaming data to the Waylay platform, it provides its unique identifier, i.e. a resource name. Each resource can push multiple parameters to the Waylay broker. The Waylay framework will automatically distribute the resource parameters to the tasks and nodes with the corresponding resource name. E.g. with the ‘execute on data’ option described below, the sensors with the corresponding resource name will automatically get invoked when new streamed data with the same resource name becomes available. Before any sensor execution, payload streaming data will be provided to the calling node. That way, sensor (𝛌 function code) will at the moment of invocation have access to the streaming data. The resource name can be specified at the task level and at the node level.

In case you have many sensors in your task that share the same resource name, you may want to specify it at the task level and inherit it at the node level via the $ symbol. Or if you have sensors for different resources, give them a variablename and reference them using $<variablename> at the node level. When starting the task, you can/need to provide a value for each of the defined variablenames.

We can also find all tasks, that have at least one sensor which is assosiated with that resource. task

Use placeholders inside the parameters when defining the commands of a resource type

This comes in handy if you want to abstract vendor specific command payload encoding from the rules’ business logic. A classical B2B example is where there are two appliances with different firmware versions exposing the same command API but with slightly different command encoding requirements. You can abstract this difference from the rule builder using this feature.

For example, the below screen shows the list of possible actuator commands for a Resource Type MystromLamp. In this example, when the command ‘TurnOn’ is called in the business rule, the Waylay rules engine will automatically search the resource’s meta data for ‘uid’ and replace the placeholder {{uid}} with the value found in the meta data before the ‘TurnOn’ command is sent to the lamp.

task