Skip to content

Commit

Permalink
Merge pull request #25 from aljoshakoecher/develop
Browse files Browse the repository at this point in the history 
Improved documentation
  • Loading branch information
@aljoshakoecher
aljoshakoecher committed Nov 8, 2021
2 parents df46e49 + 3fbd633 commit fde1cd7
Show file tree
Hide file tree
Showing 3 changed files with 118 additions and 45 deletions.
44 changes: 44 additions & 0 deletions CITATION.cff
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Koecher"
given-names: "Aljosha"
orcid: "https://orcid.org/0000-0002-7228-8387"
- family-names: "Vieira da Silva"
given-names: "Luis Miguel"
- family-names: "Kaltwasser"
given-names: "Marco"
title: "SkillUp - The skill development framework"
version: 1.0.0
date-released: 2021-11-08
url: "https://github.com/aljoshakoecher/skill-up"
preferred-citation:
type: conference-paper
authors:
- family-names: "Koecher"
given-names: "Aljosha"
orcid: "https://orcid.org/0000-0002-7228-8387"
- family-names: "Hildebrandt"
given-names: "Constantin"
- family-names: "Caesar"
given-names: "Birte"
- family-names: "Bakakeu"
given-names: "Jupiter"
- family-names: "Peschke"
given-names: "Joern"
- family-names: "Scholz"
given-names: "Andre"
- family-names: "Fay"
given-names: "Alexander"
doi: "10.1109/ETFA46521.2020.9211933"
collection-title: "2020 25th IEEE International Conference on Emerging Technologies and Factory Automation (ETFA)"
year: 2020
isbn: 978-1-7281-8956-7
conference:
name: 2020 25th IEEE International Conference on Emerging Technologies and Factory Automation (ETFA)
location: Vienna, Austria
date-start: 2020-09-08
date-end: 2020-09-11
start: 1013 # First page number
end: 1018 # Last page number
title: "Automating the Development of Machine Skills and their Semantic Description"
91 changes: 60 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,59 @@
# Skill-Up
*Skill-based engineering* is a term used in automation research for a couple of approaches trying to describe machines and their functionalities as skills. *Semantic Web Technologies* like ontologies using the Web Ontology Language (OWL) are seen as a promising solution to create such descriptions in a machine-readable and vendor-neutral way. But using OWL models places high demands on machine engineers and software developers involved in developing a machine. In addition to programming the machine behavior - which has to be done anyway - they have to provide an interface to invoke this machine behavior and they have to create an ontological description for this interface. This leads to a lot of challenges: There are very few ontology experts in automation industry and these tasks are both tedious and error-prone when done manually.<br>
**This is where Skill-Up comes into play.** <br>
<div align="center">
<img width="400px" src="https://github.com/aljoshakoecher/skill-up/blob/documentation/images/images/SkillUp-Icon.png?raw=true">
</div>
<h1 align="center">Skill Development Framework</h1>


*Skill-based engineering* is a term used in automation research for a couple of approaches trying to describe machines and their functionalities as skills. *Semantic Web Technologies* like ontologies using the Web Ontology Language (OWL) are seen as a promising solution to create such descriptions in a machine-readable and vendor-neutral way. But using OWL models places high demands on machine engineers and software developers involved in developing a machine. In addition to programming the machine behavior - which has to be done anyway - they have to provide an interface to invoke this machine behavior and they have to create an ontological description for this interface. This leads to many challenges: There are very few ontology experts in automation industry and these tasks are both tedious and error-prone when done manually. **This is where Skill-Up comes into play.**

Skill-Up is a Java-framework which can be used to develop machine skills without any additional effort. You can implement your machine behavior as plain Java classes only adding a few annotations, everything else will be generated automatically. In a bit more detail, these things that are generated are:

* A [state machine according to ISA 88]([https://link](https://github.com/aljoshakoecher/ISA88-StateMachine)) containing your behavior. The state machine makes sure the behavior is only executed in the right state.
* An invocation interface (either via RESTful webservices or OPC UA) which can be used to interact with the state machine (trigger commands, get current state)
* An ontological description of the state machine and the invocation interface. This description can be consumed by other systems that want to interact with a machine.

Skill-Up is based on this [Machine Capability and Skill Model](https://github.com/aljoshakoecher/machine-capability-model). For more details about the model, please visit this repository.
Skill-Up is based on this [Machine Capability and Skill Model](https://github.com/aljoshakoecher/machine-capability-model). For more details about the model, please visit this repository.

## Setup
Skill-Up is implemented as a collection of OSGi bundles. You can start a *Skill Runtime* (i.e. an OSGi container running certain necessary bundles as well as Skill-Up) on a machine's controller and manage (add, start, stop) skills while others are running.
:construction: Please note that SkillUp is best used in combination with SkillMEx which is published to Github soon :construction:

We will provide a ready-to-use *Skill-Runtime* very soon...
## Setup
Skill-Up is implemented as a collection of OSGi bundles. You can start a *SkillUp Runtime* (i.e. an OSGi container running certain necessary bundles as well as Skill-Up) on a machine's controller and manage (add, start, stop) skills while others are running.
A preconfigured OSGi container based on *Apache Felix* is provided in the releases. If you want to setup your own OSGi container, you need to have all the bundles of SkillUp along with their dependencies. A dedicated list of required bundles will be provided soon:

## Usage
We recommend to use one of the example projects as a template to get started. A detailed step-by-step guide will be coming soon...
After setting up your IDE, programming a skill is actually quite simple. If you look at the examples below, you can see that you just have to add some annotations to your otherwise conventional Java class. These annotations are:
SkillUp distinguishes between *modules* (i.e., machines that may provide skills) and *skills* (i.e., machine functionality that is provided by a module and can be executed). Both modules and skills can be run inside a SkillUp runtime. Note that you have to have an OSGi bundle of a module running inside your SkillUp runtime before you can add skills.
After setting up your OSGi container, you can develop your own modules and skills and deploy them inside a SkillUp runtime. Please check the wiki articles on [how to develop your own module](https://github.com/aljoshakoecher/skill-up/wiki/Step-by-step-instructions-for-creating-a-module) as well as [how to develop your own skill](https://github.com/aljoshakoecher/skill-up/wiki/Step-by-step-instructions-for-creating-a-skill)
Furthermore, there are example projects to help you get started. If you look at these examples, you can see that you just have to add some annotations to your otherwise conventional Java class. There are annotations to create modules and skills that are shown below.

### Module
`@Module` is the only annotation that is needed in order to decorate a module class. It is a class annotation that accepts two arguments
* `moduleIri`: This IRI will be used for the module individual when creating the semantic description
* `capabilityIri`(optional): Currently not used
* `description` (optional): A human-readable description of this module



### @Skill
`@Skill` is a class annotation which is mandatory in order to mark your class as a skill. It is needed by Skill-Up to get notified about a newly deployed skill in the Skill-Runtime.
`@Skill` is a class annotation which is mandatory in order to mark your class as a skill. It is needed by Skill-Up to get notified about a newly deployed skill in a SkillUp runtime.
You can pass in additional arguments to `@Skill`:
* type (string): Can either be "OpcUaSkill" or "RestSkill"
* `skillIri`: This IRI will be used for the skill individual when creating the semantic description
* `capabilityIri`: IRI of the capability that this skill is able to execute
* `moduleIri`: IRI of the module that this skill belongs to. Important: A skill can only be activated if a module bundle is already deployed
* `type`: This is used to specify the implementation of a skill. A class extending `SkillType` has to be passed as a value. Currently, there are only two possible candidates: `OpcUaSkillType` (for skills implemented via OPC UA) and `RestSkillType` (for skills implemented as web services).
* `description` (optional): A human-readable description of this skill

### @SkillParameter
This is a field annotation that can be used to mark certain fields as parameters of your skill. Specifying fields as `@SkillParameter` creates an interface to change these later on when the skill is used.
This is a field annotation that can be used to mark certain fields as parameters of your skill. Specifying fields as `@SkillParameter` creates an interface to change these parameters at runtime when the skill is used. This annotation accecpts arguments:
* `name` (optional): Typically, the variable name will be used when creating the semantic skill mode. This argument can be used to use a different name in the model.
* `description` (optional): A human-readable description of this skill
* `isRequired`: Specifies whether or not this parameter has to be set on skill invocations
* `option` (optional): A string array of possible options. Can be used in case a parameter should only accept certain values.

### @SkillOutput
`@SkillOutput` is another field annotation that defines which fields will be returned by the skill. Note that skill execution is asynchronous and that other systems can get result information when a skill is completed
`@SkillOutput` is another field annotation that defines which fields will be returned by the skill. Note that skill execution is asynchronous and that other systems can get result information when a skill is completed. This annotation accecpts arguments:
* `name` (optional): Typically, the variable name will be used when creating the semantic skill mode. This argument can be used to use a different name in the model.
* `description` (optional): A human-readable description of this skill
* `isRequired`(optional): Specifies whether or not this parameter has to be set on skill invocations

### ISA88 state annotations
Together with `@Skill` these annotations are important to create a functioning skill. There is a total of 11 annotations in this group that represent so-called active states of the ISA 88 state machine. These annotations have to be placed in front of a method. Using these annotations makes sure that this method is executed in the corresponding state of the ISA 88 state machine.
Expand All @@ -44,26 +71,28 @@ Together with `@Skill` these annotations are important to create a functioning s
* @Unsuspending: Ensures that the method following this annotation is executed in Unsuspending state


If you have your *Skill-Runtime* up and running, you can deploy skills by simply dropping them into the *include*-directory of your skill runtime. Skill-Up will pick up the new skill and publish it as a new skill.
Build your module and skill classes as OSGi bundles and fire up your SkillUp runtime. You can then deploy a module by dropping the according bundle into the *include*-directory of your SkillUp runtime. Skill-Up will pick up the module and register it to SkillMEx.
After deploying a module, you can deploy skills of that module (i.e., with the same `moduleIri`). SkillUp will pick up every skill and register it to SkillMEx from where skills can be executed.

## Examples
You can already find examples in the examples folder. They will be explained here soon...
Check out the example module and skills in the examples folder to get started. Feel free to create an issue if necessary.

```Java
@Skill(type = "OpcUaSkill")
public class AdditionSkill {
@SkillParameter
int a,b;

@SkillOutput
int result;

@Execute
public void aPlusB() {
this.result = this.a + this.b;
}
## How it works
:construction: The way SkillUp works will be explained soon :construction:

## How to cite
We are excited about everyone using SkillUp in their own applications. If you use SkillUp in research, please consider giving credit by citing the following paper that initially introduced SkillUp:

```
@inproceedings{KHC+_AutomatingtheDevelopmentof_2020,
author = {Köcher, Aljosha and Hildebrandt, Constantin and Caesar, Birte and Bakakeu, Jupiter and Peschke, Joern and Scholz, Andre and Fay, Alexander},
title = {{Automating the Development of Machine Skills and their Semantic Description}},
pages = {1013--1018},
publisher = {IEEE},
isbn = {978-1-7281-8956-7},
booktitle = {{2020 25th IEEE International Conference on Emerging Technologies and Factory Automation (ETFA)}},
year = {9/8/2020 - 9/11/2020},
doi = {10.1109/ETFA46521.2020.9211933},
shorthand = {KHC+20}
}
```

## How it works
One bundle in our Skill-Runtime is responsible for tracking new bundles that contain a @Skill-Annoation
28 changes: 14 additions & 14 deletions annotations/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,18 @@
<artifactId>skillup.parent</artifactId>
<version>1.0.0</version>
</parent>

<artifactId>skillup.annotations</artifactId>

<packaging>bundle</packaging>
<name>SkillUp Annotations</name>
<description>Contains annotations that are needed to develop modules and skills using SkillUp</description>
<url>https://github.com/aljoshakoecher/skill-up</url>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<developers>
<developer>
<name>Aljosha Koecher</name>
Expand All @@ -33,31 +33,31 @@
<organizationUrl>http://www.hsu-hh.de/aut</organizationUrl>
</developer>
</developers>

<licenses>
<license>
<name>MIT License</name>
<url>http://www.opensource.org/licenses/mit-license.php</url>
</license>
</licenses>

<distributionManagement>
<snapshotRepository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<url>https://s01.oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
<url>https://s01.oss.sonatype.org/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>

<scm>
<connection>scm:git:git://github.com/aljoshakoecher/skill-up</connection>
<developerConnection>scm:git:ssh://github.com/aljoshakoecher/skill-up</developerConnection>
<url>https://github.com/aljoshakoecher/skill-up</url>
</scm>

<build>
<plugins>
<plugin>
Expand All @@ -78,15 +78,15 @@
</instructions>
</configuration>
</plugin>

<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.8</version>
<extensions>true</extensions>
<configuration>
<serverId>ossrh</serverId>
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
<nexusUrl>https://s01.oss.sonatype.org/</nexusUrl>
<autoReleaseAfterClose>true</autoReleaseAfterClose>
</configuration>
</plugin>
Expand Down Expand Up @@ -118,7 +118,7 @@
</plugin>
</plugins>
</build>

<profiles>
<profile>
<id>release-sign-artifacts</id>
Expand Down Expand Up @@ -148,5 +148,5 @@
</build>
</profile>
</profiles>

</project>

0 comments on commit fde1cd7

Please sign in to comment.