Sensor's network

Observations and observation types

Observations are the kind of objects that are used by sensors, devices, pieces of software (things in general) to notify about state change, sensor's readings, etc. Like thing's instances, or any other object in our architecture, they have a type that defines its attributes. Usually we differentiate between an observation instance and an observation type but the former is usually called just observation.

Observation types, as any other type, is a JSON-LD that defines the attributes of an observation.

To be able to create an observation you need to firstly define its type. When you create a new observation type, you will find there are a number of core attributes that are present in all observations. In addition to those like name and description that you can find in any object, you will find:

• (See Observations types)

topic 

This is a String. It contains the destination path where this observation will be stored. We will explain later in this document the characteristics of a topic. Like paths in a filesystem you can specify a list of tokes separated by the character '/' to express an specific position in topic's tree. For instance, you can have /amtech as a topic but you can also express something more specific like /us/nevada/las_vegas/hotel_x/main_parking/parking_lot_1/movement_sensor as the topic of an observation generated by the movement sensor that is located in the parking lot 1 of the main parking of Hotel X in Las Vegas. A topic specification can have placeholders. Those will be explained later in this document. Example:

 {
   ...
   "topic": "/#{tenantId}/#{country_code}/#{city}",
   ...
 }

(See Topics)

producer 

A String used to specify the producer of this observation.

location 

If known, this is the location where this observation took place. It's expressed as a JSON String that contains a WKT specification. The structure of this JSON is explained in the Location's page.

ocurrence_time 

This is the date and time an observation occurred. It's specified by the producer of the observation.

detection_time 

This is the date and time an observation is detected in the system. The producer can specify it but it will always be overriden by our system.

targetthings 

This is a JSON String that specified the things that are affected in some way by this observation. This is a concept that is better explained in the Observer's page. Example:

 
 {
   ...
   "targetthings": "[
     {
         \"thingType\": \"/amtech/linkeddata/types/composite/entity/smartphone\", 
         \"thingsId\": [\"phone#{city}\"]
     }, {
         \"thingType\": \"/amtech/linkeddata/types/composite/entity/truck\", 
         \"thingsId\": [\"truck#{country_code}\"]
     }]",
   ...
 }

Simulator

• (See Simulator)

The simulator is a page in the Creator's UE that allows the user to send observations as if they were generated by a thing in the IoT. There you can create your own observation's instances. Once created, you can select one or more observations and hit the Send button in order to run a simulation. Observations are actually sent to the sensor's network and you can see the result by consuming then from the corresponding topic.

Topics

A topic is a UTF-8 string, which is used by the broker to filter messages for each connected client. A topic consists of one or more topic levels. Each topic level is separated by a forward slash (topic level separator).

   /sensor_network/observation_errors/graiEPC

In comparison to a message queue a topic is very lightweight. There is no need for a client to create the desired topic before publishing or subscribing to it, because a broker accepts each valid topic without any prior initialization.

• each topic maintains the observation types (semantic) that have been sent to it. (See Observations and observation types)
• Restful API to send and get observations type (See Observation instances)
• web-sockets to asynchronous subscribe to observations (See Asynchronous Observation instances)
• by configurations these observatios are manteined for one hour
• this observations are server to a user one time per topic
  • if the user has access to it
• How it works

Enrichment

You can find more information about this topic in the observation enrichment page.

CRUD observation

When a CRUD operation is executed on a thing instance, and the type of the instance have been configured to send crud observations, an observation instance of type observationresourcecrud is sent to the configured topic (See Topics):

• if the thing type produces the observation type observationresourcecrud.(See Thing types)
• if there is a activity with observation configuration for the thing type and includes the observation type observationresourcecrud.(See Observation production configuration)

The following example illustrates a crudoperation PUT to resource @id /amtech/things/observations/llrpAntennaInRoom5586417595299841, the proId changed from oldvalue false to newvalue true (See Observations and observation types)

    {
        "topic": "/thingsInBoardroom/ccAsync/",
        "_tenant": "amtechdemocreator",
        "targetthings": "[]",
        "@type": "/amtech/linkeddata/types/composite/observation/observationresourcecrud",
        "propId": "sendSmoothingLost",
        "resourceuri": "/amtech/things/entities/LLRPAntenna/llrpAntennaInRoom",
        "resourcetype": "/amtech/linkeddata/types/composite/entity/LLRPAntenna",
        "newvalue": "true",
        "guesttenants": [],
        "oldvalue": "false",
        "crudoperation": "PUT",
        "producer": "",
        "detectiontime": "Tue Apr 26 22:35:57 UTC 2016",
        "occurrencetime": "Tue Apr 26 22:35:56 UTC 2016",
        "@id": "/amtech/things/observations/llrpAntennaInRoom5586417595299841",
        "_user": "amtechdemocreator@amtech.mx"
    }

This observation allows reasoners to focus just on monitoring the changes to specific things' properties, independent of what originated the transformation of the Thing.

Sensor network error

Occurs when there is an error in the process of delivering an observation to its destination topic. Usually occurs in the process of observation enrichment

• topic "/sensor_network/"
  • An observation type observationoutputmsg get send to the sensor network topic /sensor_network/observation_errors/[observationTypeName] in the following example is an observation type observationresourcecrud sent with a wrong topic value "message": "Failed registering topic for observation"

     {
        "topic": "/sensor_network/observation_errors/observationresourcecrud",
        "_tenant": "m2mcreator",
        "@type": "/amtech/linkeddata/types/composite/observation/observationoutputmsg",
        "resource": "{\"topic\":\" /helloWorld/asynch\",\"_tenant\":\"m2mcreator\",
        \"targetthings\":\"[]\",
        \"@type\":\"/amtech/linkeddata/types/composite/observation/observationresourcecrud\",
        \"propId\":\"hwgreetingLabel\",\"resourceuri\":\"/amtech/things/entities/HelloWorld/helloWorld\",
        \"resourcetype\":\"/amtech/linkeddata/types/composite/entity/HelloWorld\",
        \"newvalue\":\"heyWithError\",\"guesttenants\":[],
        \"oldvalue\":\"hey\",\"crudoperation\":\"PUT\",
        \"producer\":\"helloWorld\",\"detectiontime\":\"2016-04-22T18:33:11.481Z\",
        \"@id\":\"/amtech/things/observations/helloWorld5226521372857087\",
        \"occurrencetime\":\"2016-04-22T18:33:10.948Z\",\"_user\":\"m2mcreator@amtech.mx\"}",
        "_name": "idbf740e7d83064ba492c9ca33d20617a0",
        "resourcetype": "/amtech/linkeddata/types/composite/observation/observationresourcecrud",
        "message": "Failed registering topic for observation",
        "guesttenants": [],
        "producer": "enrichment-topology",
        "detectiontime": "Fri Apr 22 18:33:11 UTC 2016",
        "@id": "/amtech/things/observations/6de7bf42-2ea6-4140-a8f4-a427bc119701",
        "success": false,
        "messagedetail": 
        "Error registering topic '/amtech/things/eventsources/ ': Resource /amtech/things/eventsources/  is not valid for its type definition. Property @idcannot contain blank spaces. ",
        "_user": "m2mcreator@amtech.mx"
    }