## SAREF patterns for commands

NOTE: The text in this page is taken from ETSI TS 103 548, and therefore falls under the ETSI IPR Policy

### Introduction

In SAREF, commands represent the lowest-level directives a device supports and exposes to some network. Commands can act upon (OP saref:actsUpon and its sub-properties) features, properties, or states. While commands are independent of any function, commands of interest are commands actually supported by a function of interest.

The figure below illustrates the main classes and properties in the SAREF Core patterns for Commands.

SAREF Core pattern for Commands: commands and commands of interest

### Commands

#### Creating commands

SAREF extensions should create instances of the class saref:Command, such that they can be reused in different SAREF applications.

SAREF applications may also create specific instances of the class saref:Command.

The identifier and the label of an instance of command should end with "Command", and its comment may mention "command kind" or "kind of command".

EXAMPLE:

    ex:OpenCommand a saref:Command ;
                rdfs:label "Open command"@en ;
                rdfs:comment "A command to put some feature of interest in an open state. This command has no input or output parameter."@en ;
                saref:controls ex:OpenClose .

#### Specializing commands

SAREF extensions may define a taxonomy of commands using `skos:broader` and `skos:narrower`.

The identifier, the label, and the comment of an instance of saref:Command should explicit its position in the taxonomy of commands.

NOTE: The set of commands is specialized down the taxonomy of functions. The observed or controlled property or state may be specialized, input and output may be added, specialized, etc.

EXAMPLE: ex:OffCommand, may be a specialization of ex:OnOffCommand.

#### Categorizing commands

SAREF extensions and applications may define categories of commands by creating sub-classes of saref:Command.

The identifier, the label and the comment of a sub-class of saref:Command should explicit its position in the hierarchy of function classes.

The identifier, and the label of a command class should end with "CommandCategory", and its comment should mention "command category" or "category of commands".

EXAMPLE: The class ex:TemperatureInputCommandCategory groups commands that take the ex:Temperature property as input.

    ex:TemperatureAsInputCommandCategory a owl:Class ;
                    rdfs:subClassOf saref:Command, [
                        a owl:Restriction ;
                        owl:onProperty saref:hasInput;
                        owl:hasValue ex:Temperature ] ;
                    rdfs:label "Temperature As Input Command Category"@en ;
                    rdfs:comment "Category of commands that take a temperature as input."@en .

### Commands of interest

#### Creating commands of interest

SAREF extensions should not create specific instances of the class saref:CommandOfInterest, as they are meant to be specific to an application. The only exception to this provision is if the associated function of interest is intended to be used by most applications of the SAREF extension.

Given a command of interest belongs to exactly one function, itself belonging to exactly one device, its identifier should consist of the identifier of the function, followed by character '/' and a local identifier for the command.

A specific instance of the class saref:CommandOfInterest should link to its kind (an instance of saref:Command) using property saref:hasCommandKind, and to the unique function of interest it is a command of using OP saref:isCommandOfInterestOf.

#### Categorizing commands of interest

SAREF extensions should not define sub-classes of saref:CommandOfInterest, as this would duplicate information already part of the taxonomy of commands.

### Specializing OPs and DPs related to commands

SAREF extensions and applications shall not define sub-properties of the following properties:

- saref:hasCommand
- saref:isCommandOf
- saref:hasMandatoryCommand
- saref:hasOptionalCommand
- saref:hasCommandOfInterest
- saref:isCommandOfInterestOf
- saref:hasCommandKind

SAREF extensions and applications may define sub-properties of OP saref:hasInput. The identifier, the label, and the comment, of such a sub-property should contain "Input".

EXAMPLE 1: ex:hasTargetColorInput and ex:hasTransitionTimeInput.

SAREF extensions and applications may define sub-properties of OP saref:hasOutput. The identifier, the label, and the comment, of such a sub-property should contain with "Output".

EXAMPLE 2: ex:hasOutputTemperature, ex:hasOutputHumidity.