5. USB camera

ThingFacet is a reusable TQL component that defines the software interactions with a "thing" and represent the "thing" in the software. A "thing" can be sensors, actuators, devices, or a particular aspect or function of a more complex machine. A ThingFacet has a name, Model Attributes and Actions.

Attributes

Attributes are containers of values. They can be used for the following purposes in ThingFacets:

(1) Store parameters required to make a protocol specific invocation to the thing, such as <String Name="InterfacePort"/>

(2) Store information received from the thing, such as <Number Name="TempValue"/> (The TempValue from the temperature sensor)

(3) Hold fixed information about the thing, such as <String Name="Unit" default="Celsius"/>

(4) Act as control variables - variable that can activate certain actions. They are called "actionable attributes". Actionable attributes are linked with one or more actions in the same ThingFacet by a modifier "KnownBy". For example: <Number Name="TempValue" KnownBy="SerialReadAction"/>

Actions

Action is where the processes to interact with things are defined.

An example of Camera ThingFacet.

An Action is a named element that describes a unit of executable functionality.

An Action has a name:  

#
Action(Name: "RotateCameraAction", Documentation: "Simple Action to Rotate IP-based Camera by x degrees") 

An Action must define executable code in any Atomic Domain Languages (Workflow, FacetScript, TQL, Subscribe, Sequence) or any of their combinations, within one of the following elements:

• ThingFacet (see ThingFacet actions)
• AppFacet (see AppFacet actions)
• Subscribe
• Sequence

NOTE: In the case of ThingFacet or AppFacet an Action must start with a Workflow.

Action is associated with attribute(s)

An Action must be associated or attached to a model attribute. In ThingFacets or AppFacets, an Action is associated with an model attribute of the same ThingFacet or AppFacet using the "KnownBy" modifier as below. The associated attribute becomes an actionable attribute.

#
Double(Name: "RotateValue", KnownBy: "RotateCameraAction")

Please refer to <subscribe> and <sequence> for their respective action associations.

See also Associate multiple thing actions.

Action results in changes of the "Known" value(s) of any attributes

From the Action, using the output of the workflow, you can update any attributes of the model. Note that It is always the "Known" value of the attribute that will be updated by Actions. In this example, Action is changing the State and Image attributes.

#
Output(name: "Result", as: "ActionResult"):
  Value:
    State: "[%:[%:@Output:%]/if([:IOK:]) then 'ON' else 'OFF':%]"
    Image: "[%:[%:@Output:%]/if([:IOK:]) then Invoke/GetImage/Message/Value/text() else '/img/no-image.jpg':%]"

Note: the output of the workflow can update any attribute of the model. This is not limited to the actionable attribute.

Action is triggered by the modification of associated (KnownBy) attribute values

Trigger is an execution phase of an Action. Execution of an Action is asynchronous and can be triggered in any number of ways. Please refer to <subscribe> and <sequence> for their respective action triggers.

In ThingModels and AppModels any updates to the associated attribute(s) values will trigger the Action. This include the initialization of the attributes (i.e. when it first acquires its value). The attribute value updates can only be achieved via TQL queries, in one of the following forms: 

• External applications using TQL queries to update the value of the attributes. This includes the following example of a Save query to instantiate the model. Here giving the attribute RFID a value of $Null( ) will trigger the Action "KnownBy" this attribute.
• Internally TQL queries updating the value of the attributes (e.g. TQL queries can be used by models to update values of other model's attributes).
  
  

#
Query:
  Save(format: "version,current"):
    RfidReader(ReaderId: "R1", URL: "perif://"):
        RFID(value: "$Null()", version: "1")

See also Automatic Action trigger.

A workflow consists of a sequence of tasks that are orchestrated and repeatable. Each task may process events, generate events, or process information. A workflow can be defined as part of an Action or as part of a Query.

Workflows are defined by Workflow Definition Language (WDL). Workflow can have a WorkflowId (wid). In run time, a workflow can have multiple instances (or called processes). Each process or instance is a single incarnation of the workflow definition.

TQL workflow should not be confused with business workflows. Business workflow is a set of business activities driven by data exchanges, work executions and people interactions. TQL workflow is a sequence of tasks that are strictly computer system based and purely data driven. So TQL workflow can execute very "low level" device communications such as messaging, as well as very "high level" application logic. 

A task can have the following structure: 

Input - any data which is required for the task to be started. Unless all inputs are available, the task will wait.

Output - any data which is generated by the task for externals to consume. One task's output may be the input for another task in the same workflow.  

Invoke - the process part of the task. Invoke may execute script, listen to protocol handler or send data to protocol handlers.

The sequence between multiple tasks in the same workflow is driven by the dependencies between their inputs and outputs. Since tasks generally only start on receiving their inputs, their sequences are only determined instance by instance at runtime.

<Workflow Limit="1" Live="1" Timeout="-1">
	<Task name="Main" while="true">
		<Event name="Argument" as="ActionArgument" />
		<Invoke name="InvokeSerialRead" waitFor="Argument" get="perif://">
			<Message>
				<Value>
					...
				</Value>
			</Message>
		</Invoke>
		<Output name="Result" as="ActionResult">
			<Value>
				...
			</Value>
		</Output>
	</Task>
</Workflow>

Workflow contains one or more sequential or parallel, single time execution or repeatable tasks.

ActionArgument is automatically passed argument to the action of a ThingModel or AppModel (instance) by A-Stack at the action trigger step.

• ActionArgument contains both internal and user-defined attributes of the ThingModel / AppModel instance that triggered the action.
• ActionArgument is local and transient - any changes made to the ActionArgument does not get reflected in the original copy of ThingModel / AppModel.

Example: Here is the ThingModel and ThingFacet (Partial Action) Definition for a Phidget Servo Motor

#
ThingFacet(Name: "PhidgetServoFacet"):
  String(Name: "ServoProtocolURL", Default: "phid://")
  String(Name: "DeviceInterfaceIndex")
  String(Name: "PhidgetDeviceType")
  Integer(Name: "ServoAngle", KnownBy: "PhidgetServoAction")
  Action(Name: "PhidgetServoAction", Documentation: "Control Servo Motor"):
    Workflow Limit: "1", Live: "1", Timeout: "-1"):
      Task(Name: "Main", while: "true"):
        Event(Name: "Argument", as: "ActionArgument")
          #...
ThingModel(Name: "PhidgetServoModel", Combines: "PhidgetServoFacet"):
  Sid(Name: "PhidServoId")

Here is the Phidget Servo Motor Instance creation TQL Query that triggers an Action

#
Query:
  DeleteAll:
    PhidgetServoModel:
      PhidServoId(ne: "")
  Create:
    PhidgetServoModel:
      ServoProtocolURL: phid://
      PhidgetDeviceType: PhidgetAdvancedServo
      DeviceInterfaceIndex: 0
      ServoAngle: 110

Here is the ActionArgument Structure that is passed by A-Stack

#
Event:
  Argument:
    PhidServoId: KNI5JYVPAAAAUAABA4ONNHF2
    QName: 
      Atomiton.PhidgetServos.PhidgetServoModel
    $Guid:
      "#f3guorsmvr4qhomryacl5m3dha3ctaoe"
    $sid:
      KNI5JYVPAAAAUAABA4ONNHF2
    PhidgetDeviceType(Value: "PhidgetAdvancedServo", Known: "PhidgetAdvancedServo", Order: "", Version: "1", Timestamp: "1457366819505", DateTime: "2016-03-07 08:06:59.505"
      QName: "Atomiton.PhidgetServos.PhidgetServoModel.PhidgetDeviceType", FName: "PhidgetDeviceType")
    ServoAngle(Value: "110", Known: "110", Order: "", Version: "1", Timestamp: "1457366819505", DateTime: "2016-03-07 08:06:59.505", QName: "Atomiton.PhidgetServos.PhidgetServoModel.ServoAngle"
      FName: "ServoAngle")
    DeviceInterfaceIndex(Value: "0", Known: "0", Order: "", Version: "1", Timestamp: "1457366819505", DateTime: "2016-03-07 08:06:59.505"
      QName: "Atomiton.PhidgetServos.PhidgetServoModel.DeviceInterfaceIndex", FName: "DeviceInterfaceIndex")
    ServoProtocolURL(Value: "phid://", Known: "phid://", Order: "", Version: "1", Timestamp: "1457366819503", DateTime: "2016-03-07 08:06:59.503"
      QName: "Atomiton.PhidgetServos.PhidgetServoModel.ServoProtocolURL", FName: "ServoProtocolURL")

1457663102004 is same as Fri, 11 Mar 2016 02:25:02 GMT

2016-03-10 18:25:02.004

SimpleModel.MyModels.VendorInfo.vendorName given that VendorInfo is defined within

$Guid here is a global unique identifier of this model definition

$Sid is a unique Identifier of this Model Instance. Note that this value will be same as PhidServoId that is defined by PhidgetServoModel Thing Model using type Sid.

Accessing ActionArgument:

ActionArgument values can be accessed using standard Template Processor (TP) Notation. For example:

[%:Event.Argument.PhidgetDeviceType.Value:%]

An actionable attribute is a model attribute with a modifier of "KnownBy" pointing to one or multiple Action(s). For example:

String(name: "Image", KnownBy: "SyncImage")

String(name: "State", KnownBy: "SyncImage,SyncPreset")

An actionable attribute defines the active property of a ThingFacets or AppFacets.

In runtime, an actionable attribute will activate the associated Action(s) and their workflows whenever its value is modified.

For more on the relationship between Actions and actionable attributes, see here.

A model is a definition of a container, which represents the functionality or knowledge about some kind of entity. At run time, a model can be instantiated into model instances. Models are defined by Thing Definition Language (TDL). 

 In general, there are three types of models in an IoT application:

• ThingModel - representing any entity external to the system that can have interactions with the system (e.g. exchanging messages). These "things" can be sensors, actuators, machines, or other devices.
• DataModel - representing a data structure.
• AppModel - representing any unit of application logic which can contain one or more processes. These processes may interact with other components within the system (e.g. other Models) or with external applications.

The basic structures of Models

• A name
• A list of Attributes
• A number of Actions (only ThingModels and AppModels have Actions)
• A number of Constraints (including Unique)

All models by default contain an Attribute of type SystemId (or Sid). If Sid is not defined by the author of the model, system will assign Sid to the model.

Model "combines" model facets

To increase reusability, model facets are adopted as reusable units.

There are two types of model facets:

• ThingFacets
• AppFacets

Model facets have the same structural components of Models (name, attributes, actions, constraints). However, model facets are not instantiated or persisted. They can only be "combined"  as part of a model, with the model being instantiated, and persisted.

• ThingModel can combine ThingFacets;
• AppModel can combine AppFacets;
• There is no DataFacets.

As a good and recommended practice pattern, actions and attributes of a particular device logic or application logic are always defined in the model facets, and the model will acquire those attributes and actions via the keyword "combines". A model can combine multiple model facets. And vice versa, model facet can by combined by multiple model definitions.

For example:

#
ThingModel(Name: "TempSensor", combines: "TempFacetSerial"):
	Sid(Name: "sensorId");

ThingModel is one kind of Model (the other kinds are DataModels and AppModels). Therefore it has all the properties of Models (Lifecycle of models, Model Attributes, Unique and Constraints).

A ThingModel has

• a name,
• any number of Model Attributes
• and usually one or more Actions

However, as a recommended practice, the Attributes and Actions related to the interactions with an external thing (sensors, actuators, machines) are often defined in a reusable structure called ThingFacet, and combined into a ThingModel. This relationship was explained in the concept of Models and Model Facets. Application related information are often defined directly as attributes of the ThingModel.

In the following example, the ThingModel PhidgetServoModel combines the ThingFacet PhidgetServoFacet, where: 

• PhidgetServoFacet contains the device interaction specific Attributes (e.g. ServoProtocolURL) and Actions (e.g. PhidgetServoAction);
• PhidgetServoModel contains application related Attributes: PhidServoId and InstalledAtZone (assuming the Phidget servo motor is installed in a particular zone within a Greenhouse environment, which has multiple zones).
• Combines is used as a modifier of ThingModel

In the simplest case, a ThingModel may only have one single directly defined attribute of type Sid. Although not required, it is best practice to always create a ThingModel with one attribute that is of type SystemId or Sid.

#
ThingModel(Name: "PhidgetServoModel", Combines: "PhidgetServoFacet"):
    Sid(Name: "PhidServoId")
    String(Name: "InstalledAtZone")
    
ThingFacet(Name: "PhidgetServoFacet"):
    String(Name: "ServoProtocolURL", Default: "phid://")
    String(Name: "DeviceInterfaceIndex")
    String(Name: "PhidgetDeviceType")
    Integer(Name: "ServoAngle", KnownBy: "PhidgetServoAction")
    Action(Name: "PhidgetServoAction", Documentation: "Control servo motor"):
      #...

This pattern allows the ThingFacet to be a reusable artifact, and potentially combined by multiple ThingModels.

Note: One can combine multiple ThingFacets within a single ThingModel using comma separated list of ThingFacets.

For Example Esky ThingModel combining EskyPreset and EskyImage Thing Facets

#
ThingFacet(Name: "EskyPreset"):
  String(Name: "State", KnownBy: "SyncPreset")
  String(Name: "Preset", KnownBy: "SyncPreset")
  Action(Name: "SyncPreset", documentation: "Synchronize camera state and preset"):
    Workflow Limit: "1", Live: "1", Timeout: "PT20S"):
      Task(Name: "Main", while: "true"):
        Event(Name: "Argument", as: "ActionArgument")
          #...

ThingFacet(Name: "EskyImage", combines: "Login"):
  String(Name: "State", KnownBy: "SyncImage")
  Clob(Name: "Image", KnownBy: "SyncImage")
  
  #Actions
  Action(Name: "SyncImage", documentation: "Synchronize camera state and snapshot image"):
    Workflow Limit: "1", Live: "1", Timeout: "PT10S"):
      Task(Name: "Main", while: "true"):
        Event(Name: "Argument", as: "ActionArgument")

ThingModel(Name: "Esky", combines: "EskyPreset,EskyImage", documentation: "actual single instance camera model"):
  Sid(Name: "CameraId")

In summary

• ThingModels are normally used to represent and define interactions with external physical things. The specifics of interactions are often modeled via ThingFacet.
• ThingModels combine one or more ThingFacets. ThingFacets are reusable artifacts. In runtime, only instances of ThingModels are created and persisted (not ThingFacets). 
• ThingModels can contain application related information that are related to things.

When ThingModels do not have any Actions or combine any ThingFacets they are equivalent to DataModel i.e pure Attributes only.

ThingModel can be created, read, update and deleted using TQL queries.

#
Create: 
    PhidgetServoModel: 
      ServoProtocolURL: "phid://"
      PhidgetDeviceType: "PhidgetAdvancedServo"
      DeviceInterfaceIndex: 0
      ServoAngle: 110

#
Create(Status: "Success"):
  PhidgetServoModel: 
    PhidServoId: "KNJN2YRVAAAAUAABA7LIQ4Y6" 
    ServoProtocolURL(Status: "Success+Created:1:1457384153653;", Value: "phid://")
    DeviceInterfaceIndex(Status: "Success+Created:1:1457384153653;", Value: "0")
    PhidgetDeviceType(Status: "Success+Created:1:1457384153653;", Value: "PhidgetAdvancedServo")
    ServoAngle(Status: "Success+Created:1:1457384153654;", Value: "110")

#
Query: 
  Find(format: "version"):
    PhidgetServoModel as: "var.PS"):
      PhidServoId(ne: "")
  SetResponseData: 
    key: Message.Value.Find.Result.PhidgetServoModel.ServoAngle.Value
    value: 120
  Update: 
    from: Result
    Include: $Response.Message.Value.Find

#
Find(Status: "Success", Format: "version"):
  Result: 
    PhidgetServoModel: 
      PhidServoId: "KNJPIFR6AAAAUAABA67ZRBQO" 
      PhidgetDeviceType(Value: "PhidgetAdvancedServo", Version: "1")
      ServoAngle(Version: "1", Value: "120")
      DeviceInterfaceIndex(Value: "0", Version: "1")
      ServoProtocolURL(Value: "phid://", Version: "1")

#
Query: 
  DeleteAll: 
    PhidgetServoModel: 
      PhidServoId(ne: "")

#
DeleteAll(Status: "Success"):
  Result: 
    PhidgetServoModel: 
      PhidServoId: "KNJOOOBZAAAAUAABA72MMI6E"
      PhidgetDeviceType: "PhidgetAdvancedServo"
      ServoAngle: 110
      DeviceInterfaceIndex: 0
      ServoProtocolURL: "phid://"

#
Query: 
  Find(format: "all"):
    PhidgetServoModel:
      PhidServoId(ne: "")

#
Find(Status: "Success", Format: "all"):
  Result: 
    PhidgetServoModel(QName: "Atomiton.PhidgetServos.PhidgetServoModel"):
      PhidServoId: "KNJOOOBZAAAAUAABA72MMI6E" 
      PhidgetDeviceType(Value: "PhidgetAdvancedServo", Known: "PhidgetAdvancedServo", Version: "1", Timestamp: "1457384798266", DateTime: "2016-03-07 13:06:38.266", QName: "Atomiton.PhidgetServos.PhidgetServoModel.PhidgetDeviceType", FName: "PhidgetDeviceType")
      ServoAngle(Value: "110", Known: "110", Version: "1", Timestamp: "1457384798266", DateTime: "2016-03-07 13:06:38.266", QName: "Atomiton.PhidgetServos.PhidgetServoModel.ServoAngle", FName: "ServoAngle")
      DeviceInterfaceIndex(Value: "0", Known: "0", Version: "1", Timestamp: "1457384798266", DateTime: "2016-03-07 13:06:38.266", QName: "Atomiton.PhidgetServos.PhidgetServoModel.DeviceInterfaceIndex", FName: "DeviceInterfaceIndex")
      ServoProtocolURL(Value: "phid://", Known: "phid://", Version: "1", Timestamp: "1457384798265", DateTime: "2016-03-07 13:06:38.265", QName: "Atomiton.PhidgetServos.PhidgetServoModel.ServoProtocolURL", FName: "ServoProtocolURL")

In TQL, a query is any operations on the model instance data (or model data), which includes filtering, joining, and manipulations. Model instances are incarnations of the Models (or model definitions) through instantiation. The A-Stack stores the latest version of the model instance data, which is accessible to TQL Queries. See data storage for more details.

There is a special type of query which allows you to show or list the model definitions themselves. See /wiki/spaces/TQLDocs/pages/1179668 for details.

Like conventional queries, TQL queries perform CRUD operations on data. but unlike conventional database queries, TQL queries are:

(1) Current. The A-Stack maintains the latest versions of any attribute values and attribute known values based on the model definitions. For example, the latest reading of a temperature sensor value. TQL queries always return those latest versions.

(2) Model-driven. Since the model definitions define the structure of the model data, the A-Stack constructs the database queries based on the model definition to retrieve requested data or perform other CRUD operations. The model definition is NOT the data schema. Model instance data are saved in schemaless key value pairs.

(3) Actionable. Modifications of model data via TQL queries, if involving actionable attributes, can result in activation of actions, some of which may subsequently execute device actuations.

Each model attribute has both a value and a known value. Although you can "FIND" both values and known values of model attributes, you can only set values but not known values from queries. This is because the known values are reserved to be updated only by the result of Actions, which comes from external systems or external things.

TQL queries have the following standard structures:

FIND          CREATE          SAVE          UPDATE          DELETE          DELETEALL

In addition,  you can use other operations such as conditions/constraints, response modifications, iterations, etc. within the queries.