From 419f3d7197ffa9cd71a27326faf1f740492697a3 Mon Sep 17 00:00:00 2001 From: Teodor Date: Tue, 5 Nov 2024 15:31:34 +0100 Subject: [PATCH 1/4] create new script for video 13 --- .../whatiswot/13-Thing_Description/README.md | 60 +++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 Tutorials/whatiswot/13-Thing_Description/README.md diff --git a/Tutorials/whatiswot/13-Thing_Description/README.md b/Tutorials/whatiswot/13-Thing_Description/README.md new file mode 100644 index 0000000..74533fb --- /dev/null +++ b/Tutorials/whatiswot/13-Thing_Description/README.md @@ -0,0 +1,60 @@ +## Table of Contents + +- Introduction and Definition +- TD Components +- Interactions +- Protocols + +## Preliminary Script + +### Introduction and Definition + +- In this video we will provide a general overview of a fundamental concept in the Web of Things - the Thing Description, or TD. A TD acts as a unique blueprint for the respective Thing, offering a standardized way to describe its functionality and how to interact with it. + +- Thing Descriptions are written using the JSON-LD format, making it both machine and human-readable. To understand this better, let's take a look at a simple example - a smart coffee machine, and break down the components in its Thing Description: + +**Code: Complete Thing Description - Coffee Machine Example** + +```json +{ + "@context": ["https://www.w3.org/2019/wot/td/v1"], + "id": "urn:dev:ops:Coffee-Machine-1234", + "title": "Smart Coffee Machine", + "description" : "Simplified example of a smart coffee machine", + "securityDefinitions": { ... }, + "security": { ... }, + "properties": { + "coffeeBeansLeft": { ... } + }, + "actions": { + "brewCoffee": { ... } + }, + "events": { + "lowOnWater": { ... } + }, + "links": [ ... ] +} +``` + +### TD Components + +**Code: Complete Thing Description - Coffee Machine Example** + + + +- The Thing Descriptions begins with the Thing's metadata. It provides the essential information about the device, like its unique ID, title and description. + +- Then in the Definitions of Interaction Affordances we specify ways you can interact with the device, through its various properties, actions and events. The example here shows the property coffeeBeansLeft, which describes the current state of the coffee beans, the action brewCoffee, which triggers brewing and the event lowOnWater, which alerts you when the machine is low on water. We’ll explore Interaction Affordances in greater detail in the next video of this series. + +- The Security Metadata defines security requirements and mechanisms, that ensure secure access to the device by the user. + +- To enable universal understanding, we can add Semantic Annotations. These allow other systems to interpret the device’s terms and functions consistently. + +- Finally, we can also link the Thing Description to other documents, such as documentation or a user interface. + +### Ending + +- This overview should give you a solid foundation for understanding the role of Thing Descriptions in the Web of Things. + + + From 255a82e98b9da7c6188a86e5cf1b304c57d87854 Mon Sep 17 00:00:00 2001 From: Ege Korkan Date: Fri, 8 Nov 2024 12:57:20 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr --- .../whatiswot/13-Thing_Description/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Tutorials/whatiswot/13-Thing_Description/README.md b/Tutorials/whatiswot/13-Thing_Description/README.md index 74533fb..cb24ef8 100644 --- a/Tutorials/whatiswot/13-Thing_Description/README.md +++ b/Tutorials/whatiswot/13-Thing_Description/README.md @@ -9,11 +9,11 @@ ### Introduction and Definition -- In this video we will provide a general overview of a fundamental concept in the Web of Things - the Thing Description, or TD. A TD acts as a unique blueprint for the respective Thing, offering a standardized way to describe its functionality and how to interact with it. +- In this video, we will provide a general overview of a fundamental concept in the Web of Things — the Thing Description, or TD. A TD acts as a unique blueprint for the respective Thing, offering a standardized way to describe its functionality and how to interact with it. -- Thing Descriptions are written using the JSON-LD format, making it both machine and human-readable. To understand this better, let's take a look at a simple example - a smart coffee machine, and break down the components in its Thing Description: +- Thing Descriptions are written using the JSON-LD format, making it both machine and human-readable. To understand this better, let's take a look at a simple example — a smart coffee machine — and break down the components in its Thing Description: -**Code: Complete Thing Description - Coffee Machine Example** +**Code: Complete Thing Description — Coffee Machine Example** ```json { @@ -38,19 +38,19 @@ ### TD Components -**Code: Complete Thing Description - Coffee Machine Example** +**Code: Complete Thing Description — Coffee Machine Example** - + -- The Thing Descriptions begins with the Thing's metadata. It provides the essential information about the device, like its unique ID, title and description. +- The Thing Descriptions begins with the Thing's metadata. It provides the essential information about the device, like its unique ID, title, and description. -- Then in the Definitions of Interaction Affordances we specify ways you can interact with the device, through its various properties, actions and events. The example here shows the property coffeeBeansLeft, which describes the current state of the coffee beans, the action brewCoffee, which triggers brewing and the event lowOnWater, which alerts you when the machine is low on water. We’ll explore Interaction Affordances in greater detail in the next video of this series. +- Then, in the Definitions of Interaction Affordances, we specify ways you can interact with the device, through its various properties, actions, and events. The example here shows the property `coffeeBeansLeft`, which describes the current state of the coffee beans; the action `brewCoffee`, which triggers brewing; and the event `lowOnWater`, which alerts you when the machine is low on water. We’ll explore Interaction Affordances in greater detail in the next video of this series. - The Security Metadata defines security requirements and mechanisms, that ensure secure access to the device by the user. -- To enable universal understanding, we can add Semantic Annotations. These allow other systems to interpret the device’s terms and functions consistently. +- To enable universal understanding, we can add Semantic Annotations. These allow other systems to consistently interpret the device’s terms and functions. -- Finally, we can also link the Thing Description to other documents, such as documentation or a user interface. +- Finally, we can link the Thing Description to other documents, such as documentation or a user interface. ### Ending From 954da6d5f86ef782fdf4860e660f9009fa6e9b5a Mon Sep 17 00:00:00 2001 From: Teodor Penchev <119612424+Tedoshiii@users.noreply.github.com> Date: Thu, 14 Nov 2024 19:55:35 +0100 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Ege Korkan --- .../whatiswot/13-Thing_Description/README.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/Tutorials/whatiswot/13-Thing_Description/README.md b/Tutorials/whatiswot/13-Thing_Description/README.md index cb24ef8..6a9e3ef 100644 --- a/Tutorials/whatiswot/13-Thing_Description/README.md +++ b/Tutorials/whatiswot/13-Thing_Description/README.md @@ -9,7 +9,7 @@ ### Introduction and Definition -- In this video, we will provide a general overview of a fundamental concept in the Web of Things — the Thing Description, or TD. A TD acts as a unique blueprint for the respective Thing, offering a standardized way to describe its functionality and how to interact with it. +- In this video, we will provide a general overview of a fundamental concept in the Web of Things — the Thing Description, or TD. A TD acts as a unique blueprint for the respective Thing, offering a standardized way to describe its functionality and how a Consumer should interact with it. - Thing Descriptions are written using the JSON-LD format, making it both machine and human-readable. To understand this better, let's take a look at a simple example — a smart coffee machine — and break down the components in its Thing Description: @@ -17,10 +17,12 @@ ```json { - "@context": ["https://www.w3.org/2019/wot/td/v1"], - "id": "urn:dev:ops:Coffee-Machine-1234", + "@context": ["https://www.w3.org/2022/wot/td/v1.1" + {"schema":"https://schema.org/"}], + "id": "urn:uuid:0804d572-cce8-422a-bb7c-4412fcd56f06", "title": "Smart Coffee Machine", - "description" : "Simplified example of a smart coffee machine", + "description" : "Remote controllable coffee machine", + "schema:manufacturer":"ACME Corporation", "securityDefinitions": { ... }, "security": { ... }, "properties": { @@ -44,17 +46,17 @@ - The Thing Descriptions begins with the Thing's metadata. It provides the essential information about the device, like its unique ID, title, and description. -- Then, in the Definitions of Interaction Affordances, we specify ways you can interact with the device, through its various properties, actions, and events. The example here shows the property `coffeeBeansLeft`, which describes the current state of the coffee beans; the action `brewCoffee`, which triggers brewing; and the event `lowOnWater`, which alerts you when the machine is low on water. We’ll explore Interaction Affordances in greater detail in the next video of this series. +- Then, in the definitions of Interaction Affordances, we specify ways a Consumer application can interact with the Thing, through its various properties, actions, and events exposed on its network interfaces. The example here shows the property `coffeeBeansLeft`, which describes the current state of the coffee beans; the action `brewCoffee`, which triggers brewing; and the event `lowOnWater`, which alerts the Consumer when the machine is low on water. We’ll explore Interaction Affordances in greater detail in the next video of this series. -- The Security Metadata defines security requirements and mechanisms, that ensure secure access to the device by the user. +- The Security Metadata defines security mechanisms required to ensure secure access to the Thing by the Consumer application. This way the Consumer application knows what type of credentials are needed to execute different operations. -- To enable universal understanding, we can add Semantic Annotations. These allow other systems to consistently interpret the device’s terms and functions. +- To add keywords that are not part of the TD standard, we can add Semantic Annotations. These allow other systems to consistently interpret the device’s terms and functions. Here, we annotate using `schema.org` to add the name of the manufacturer, which is not part of the core TD specification. - Finally, we can link the Thing Description to other documents, such as documentation or a user interface. ### Ending -- This overview should give you a solid foundation for understanding the role of Thing Descriptions in the Web of Things. +- This overview should give you a solid foundation for understanding the role of Thing Descriptions in the Web of Things. The next videos will explain the components in detail. From e41be032bc7d8f8c2933789da54229a37e3c875b Mon Sep 17 00:00:00 2001 From: Teodor Date: Thu, 14 Nov 2024 20:10:06 +0100 Subject: [PATCH 4/4] update toc --- Tutorials/whatiswot/13-Thing_Description/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Tutorials/whatiswot/13-Thing_Description/README.md b/Tutorials/whatiswot/13-Thing_Description/README.md index 6a9e3ef..7ff8a68 100644 --- a/Tutorials/whatiswot/13-Thing_Description/README.md +++ b/Tutorials/whatiswot/13-Thing_Description/README.md @@ -2,8 +2,11 @@ - Introduction and Definition - TD Components -- Interactions -- Protocols + - Metadata + - Interaction Affordances + - Security Metadata + - Semantic Annotations + - Links ## Preliminary Script