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):

Resource concept is important in many different ways:

• we can associate metadata with a resource
• we can associate data with a resource
• we can run tasks on resources (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, resource meta model can handle different concepts of a digital twin:

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

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

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

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:

Metrics

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

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

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

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 name TurnOff, the engine will check the commands property of the resource’s metadata and see if there is a command TurnOff mapped to an actuator.

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "id" : "my_lamp",
    "uuid" : "e6b4a8c9-4b3a-4986-87cc-deeea2717f26"
    "commands" : [{
       "TurnOff" : {
         "actuator" : {
            "name": "MystromLampColor",
            "version": "latest",
            "properties" : {
              "deviceId": "e6b4a8c9-4b3a-4986-87cc-deeea2717f26",
              "hsv": "foobar",
              "power": "off",
              "config": "onoff"
            }
         }
       }
    }]
  }' "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.

Typically, B2C api’s need device specific identifiers for routing the commands to the correct device but you don’t want to bother you’re 3rd party app with those. The commands feature accomodates this by allowing metadata properties templating in the commands to actuator definition.

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, 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 metadata before the TurnOn command is sent to the lamp.

Finally the actuator is executed for the resource and the merged properties:

Send a TurnOff command for resource my_lamp

curl -i --user apiKey:apiSecret -H "Content-Type: application/json" -X POST
  -d '{
    "name": "TurnOff"
  }' "https://data.waylay.io/resources/my_lamp/commands"

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

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:

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

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 identifier. 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 identifier. E.g. with the ‘execute on data’ option described below, the sensors with the corresponding resource identifier will automatically get invoked when new streamed data with the same resource identifier 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 identifier can be specified at the task level and/or at the node level.

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

In case you have many sensors in your task that share the same resource identifier, 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.

Accessing meta data in your rule logic

There is an easy way to reference resource meta data in the properties of sensors and actuators. The format is “META.$.<meta data key>”. An example is given below

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