---
# System prepended metadata

title: Wp2 Demo meeting
tags: [wp2, ' slides']

---

---
tags: wp2, slides
title: Wp2 Demo meeting
type: slide
slideOptions:
  # Minutes alloted for a slide.
  # allottedMinutes: 1 
  # Enable slide navigation via mouse wheel
  mouseWheel: true
---

<style type="text/css">
  .reveal pre code {
    font-size: 13pt;  
  }

</style>

# SIFIS-Home Hazards
## How we fit the hazards-system in WebOfThings

---

## Hazards

- We would like to label the devices and their possible actions, so we can reason about how risky is to take an action.
- We would like to make the user aware of what could go very wrong.
- We would like to prevent at least some of their risky situations from happening.

---

## Example

- You might tell your connected oven to pre-heat
    - while asleep in bed
        - because you misplaced your phone.
            - And the app registered a click.

- `sho:FireHazard`

---

## Setup 

- WebOfThings [Thing Description](https://www.w3.org/TR/wot-thing-description/) is completely flexible, you can add semantic and functional elements [as you like](https://www.w3.org/TR/wot-thing-description/#sec-context-extensions).
- [webthings.io](https://webthings.io) has ready-to-use [Frameworks](https://webthings.io/framework/) a number of languages and platforms.
- Consuming `Things Descriptions` is fairly simple and we wrote [libsifis](https://github.com/sifis-home/libsifis-rs) on top of it and `mDNS`/`DNS-SD`.
- On top of it we built a higher-level abstraction to reason about devices (e.g. Oven, Lamps).

---

## Thing Description

<style type="text/css">
  .reveal blockquote {
    text-align: left;
  }
</style>

> The WoT Thing Description (TD) is a central building block in the W3C Web of Things (WoT) and can be considered as the entry point of a Thing (much like the index.html of a Web site). A TD instance has four main components: textual metadata about the Thing itself, a set of Interaction Affordances that indicate how the Thing can be used, schemas for the data exchanged with the Thing for machine-understandability, and, finally, Web links to express any formal or informal relation to other Things or documents on the Web.
> -- [wot-thing-description](https://www.w3.org/TR/wot-thing-description/#introduction)

---

## Thing Description

 - Textual metadata about the Thing itself
 - A set of Interaction Affordances that indicate how the Thing can be used 
 - Schemas for the data exchanged with the Thing for machine-understandability
 - Web links to express any formal or informal relation to other Things or documents on the Web.

---

## Thing Description 
### Textual metadata

- Based on [JSON-LD](https://www.w3.org/TR/json-ld11/)
- Extensible using additional Vocabularies
    - e.g. using [saref](https://saref.etsi.org/) to add better semantic descriptions.
    - We use this feature to add our `hazard labeling`

---

## Thing Description
### Interaction Affordance

- Mean for a device to self-describe how to interact with it
    - Properties
    - Actions
    - Events
- This is where our hazard labels stay 

---

## Thing Description
### Interaction Affordance

``` json
"properties": {
    "brightness": {
      "@type": "BrightnessProperty",
      "description": "The level of light from 0-100",
      "maximum": 100,
      "minimum": 0,
      "sho:Hazard": {
        "@type": "sho:FireHazard",
        "const": { "minimum": 70 },
        "type": "integer"
      },
      "title": "Brightness",
      "type": "integer",
      "unit": "percent",
        ...
    },
```

---

## Things Description
### Schemas for the data exchange

- Protocols
    - Supports HTTPS, MQTT, and COAP
    - You can extend it with custom protocols easily.
- Security scheme
    - Many [SecurityScheme](https://www.w3.org/TR/wot-thing-description/#sec-security-vocabulary-definition) already available
    - More can be added e.g. [ACE](https://www.w3.org/TR/wot-thing-description/#adding-security-schemes)

---

## Webthings.io

- Former [Mozilla](https://mozilla.org) project
    - Now fully independent
- It implements W3C WebOfThings
    - Currently a pre-standard dialect, we are helping them to update to the current standard.
- It provides frameworks to build devices.
- It provides webapps to consume devices.
    - e.g. the Webthings Gateway

---

## Webthings.io
### Frameworks
- The official frameworks include a number of languages/platforms
    - Node.js
    - Python
    - Java
    - C++ / Arduino
    - MicroPython
- Many other are available from the larger community

---

## Webthings.io
### Frameworks

- We are focusing on the [rust](https://github.com/sifis-home/webthing-rust) and [arduino](https://github.com/sifis-home/webthing-arduino) frameworks
    - The `rust` framework works on any operating system supported by the language.
    - The `arduino` framework targets bare-metal.

---

## Webthings.io / rust

- It is implemented using [actix-web](https://actix.rs) and [libmdns](https://crates.io/crates/libmdns)
    - mDNS
    - WebSockets
    - REST
- Runs on any operating system supported by `Rust`.

---

## Webthings.io / rust
### Development

- Our fork is updated to support `WoT` instead of the `Webthings` dialect.
- We already sent upstream a number of fixes, including the minimum logic needed to support additional _ontologies_.

---

## Webthings.io / arduino

- It is implemented using C++ and [platformIO](https://platformio.org/)
    - mDNS
    - WebSockets
    - REST
- Runs on ESP8266, ESP32
    - Ethernet, and WiFi101-compatible boards.

---

## Webthings.io / arduino
### Development

- We updated the library to support additional _ontologies_ already.
- We will keep this in line with **webthings-rust** so we can use __real embedded hardware__.
    - We tested its functionality already loading the firmware on a wifi-actuator acting as a Lamp.

---

# libsifis

- Consumer side of our augmented `WoT` system
- Written in `Rust`
- Based on `mdns-sd`, `reqwest` and `serde_json`

---

# libsifis
## Lower level API

- Queries mDNS for `_webthing._tcp.local.` 
- Gets all the `Things Description` through `reqwest`
- Deserializes the `Things Description` using `serde_json` to rust structs.
- It is possible to use the `things()` method to iterate over the discovered devices.

---

# libsifis
## Lower level query API

- `Iterator::filter` is the main building block to query for specific things.
- On top of this we can build higher level abstractions

``` rust

    let lamps = Context::new().things().filter(|td| {
        td.attype.contains("Light") &&
            td.attype.contains("OnOffSwitch")
    });

```

---

## libsifis
### Coming Soon

- libsifis control API
    - `Property::set<T>(prop: T)`
    - `Property::get<T>(prop: T)`
    - `Action::call<A>(args: A)`
    - `Event::subscribe<F>(cb: F)`
- libsifis C bindings

---

### SIFIS-Home Hazards Ontology (SHO)

- IRI: https://purl.org/sifis/hazards
- Includes all the hazards we identified for a smart home
- Formally defines the relationship between WoT's `InteractionAffordance` and the hazards defined within SIFIS-Home

---

# Ontology Graph

![](https://i.imgur.com/Wl2ribv.png)

<p style=font-size:20px> The class <b><span style="color: #DEAD26">Interaction Affordance</span></b> is defined within the Thing Description Ontology</p>

---


### Thing Description Example (lamp)

<div class="r-stack">
    
```json
{
   "@context":[
      "https://www.w3.org/2019/wot/td/v1",
      {
         "saref":"https://w3id.org/saref#",
         "sho":"https://purl.org/sifis/hazards#"
      }
   ],
   "id":"urn:lamp-1234",
   "title":"MyLampThing",
   "@type":"saref:LightSwitch",
   "description":"A lamp description containing hazards",
   "securityDefinitions":{
      "basic_sc":{
         "scheme":"basic",
         "in":"header"
      }
   },
   "security":[
      "basic_sc"
   ],
   "properties":{
      "status":{
         "@type":"saref:OnOffState",
         "type":"string",
         "writeOnly":false,
         "readOnly":true,
         "forms":[
            {
               "href":"https://mylamp.example.com/status",
               "op":"readproperty",
               "contentType":"application/json"
            }
         ],
         "sho:hasHazard":[
            {
               "@type":"sho:LogEnergyConsumption"
            }
         ]
      },
      "brightness":{
         "@type":"BrightnessProperty",
         "writeOnly":false,
         "readOnly":false,
         "description":"The level of light from 0 to 100",
         "links":[
            {
               "href":"/properties/brightness",
               "rel":"property"
            }
         ],
         "maximum":100,
         "minimum":0,
         "title":"Brightness",
         "type":"integer",
         "unit":"percent",
         "forms":[
            {
               "href":"https://mylamp.example.com/brightness",
               "op":"readproperty",
               "contentType":"application/json"
            }
         ],
         "sho:hasHazard":[
            {
               "@type":"sho:FireHazard",
               "riskScore":2
            },
            {
               "@type":"sho:ElectricEnergyConsumption",
               "riskScore":2
            }
         ]
      }
   },
   "actions":{
      "toggle":{
         "@type":"saref:ToggleCommand",
         "safe":false,
         "idempotent":false,
         "forms":[
            {
               "href":"https://mylamp.example.com/toggle",
               "op":"invokeaction",
               "contentType":"application/json"
            }
         ],
         "sho:hasHazard":[
            {
               "@type":"sho:FireHazard",
               "riskScore":2
            },
            {
               "@type":"sho:ElectricEnergyConsumption",
               "riskScore":2
            }
         ]
      }
   },
   "events":{
      "overheating":{
         "data":{
            "type":"string",
            "writeOnly":false,
            "readOnly":false
         },
         "forms":[
            {
               "href":"https://mylamp.example.com/oh",
               "op":"subscribeevent",
               "subprotocol":"longpoll",
               "contentType":"application/json"
            }
         ]
      }
   }
}
```

<p class="fragment fade-in-then-out"><mark style="background-color:#DEF4C6; color:#1B512D">Looking at SHO documentation...</mark></p>
<img class="fragment fade-in-then-out" src="https://i.imgur.com/tqeARy0.png" height="400" style="margin-right:30px; margin-bottom:-150px" >
<p class="fragment fade-out"> </p>
</div>

---



# Sifis-abstraction

- Higher-level *Rust* APIs built on top of the lower level `libsifis` library
- Hazards associated to an API are automatically generated from the `SIFIS-Home Hazards Ontology` as documentation

---

# Hazards

```rust
/// Type of Hazards.
pub enum Hazards {
    AirPoisoning,
    AudioVideoRecordAndStore,
    AudioVideoStream,
    ElectricEnergyConsumption,
    Explosion,
    FireHazard,
    LogEnergyConsumption,
    ...
}
```

---

# Sifis-abstraction

```rust
/// Fire hazard.
/// The execution may cause fire.
pub fn turn_on_light() {
    ...
}

/// Fire hazard.
/// The execution may cause fire.
///
/// Audio video stream.
/// The execution authorises the app to obtain a video stream with audio.
pub fn turn_on_oven() {
    ...
}
```

---

# IDE Support

- Hazards are shown as IDE's pop-ups when an API is imported
- Auto-complete functions
- Plugins are implemented by third-party developers 

---

# VSCode example

<video class="fragment fade-in" data-autoplay src="https://davidblade.altervista.org/sifis/IDErecording.mov"></video>

---

# Coming Soon

- Implement the *Category* class from `SIFIS-Home Hazards Ontology` in the tool that represents hazards as documentation for higher-level APIs