Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor: favor WoT.requestThingDescription instead of general fetch #1183

Merged
merged 6 commits into from
Dec 11, 2023
Merged

refactor: favor WoT.requestThingDescription instead of general fetch #1183

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
fe43a9c
refactor: favor WoT.requestThingDescription instead of general fetch
danielpeintner Dec 5, 2023
598140c
docs: use requestThingDescription() instead of fetch in examples
danielpeintner Dec 6, 2023
7009aad
docs: fix that WoT needs to be generated/started first
danielpeintner Dec 7, 2023
4c630a4
docs: fix examples for CoAP and HTTP w.r.t servient.start()
danielpeintner Dec 7, 2023
7bc7e88
docs: fix missing start()
danielpeintner Dec 7, 2023
237b02c
docs: remove error prefix as suggest by @JKRhb
danielpeintner Dec 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -245,7 +245,7 @@ Interacting with another WoT Thing is called consuming a Thing and works by usin
##### Fetch a Thing Description of a Thing given its URL

```javascript
WoTHelpers.fetch("http://localhost:8080/counter").then(async(td) => {
WoT.requestThingDescription("http://localhost:8080/counter").then(async(td) => {
// Do something with the TD
}
```
Expand All @@ -255,13 +255,13 @@ URLs can have various schemes, including `file://` to read from the local filesy
##### Consume a TD of a Thing, including parsing the TD and generating the protocol bindings in order to access lower level functionality

```javascript
WoTHelpers.fetch("http://localhost:8080/counter").then(async (td) => {
WoT.requestThingDescription("http://localhost:8080/counter").then(async (td) => {
let thing = WoT.consume(td);
// Do something with the consumed Thing
});
```

Things can be `consume`d no matter if they were fetched with WoTHelpers or not.
Things can be `consume`d no matter if they were fetched with `WoT.requestThingDescription()`, `WoTHelpers.fetch()` or any other mean.
`consume` only requires a TD as an `Object`, so you could also use `fs.readFile` and `JSON.parse` or inline it into your code.
As long at it results in a TD Object, you can receive it over Fax, Morse it or use smoke signals.

Expand Down Expand Up @@ -298,10 +298,10 @@ It is an asynchronous function that will take some time to complete.
So you should handle it explicitly.
Here we use the `async`/`await` functionality of NodeJS.

Declare the surrounding function as `async`, e.g., the `WoTHelpers.fetch()` resolve handler:
Declare the surrounding function as `async`, e.g., the `WoT.requestThingDescription()` resolve handler:

```javascript
WoTHelpers.fetch(myURI).then(async(td) => { ... });
WoT.requestThingDescription(myURI).then(async(td) => { ... });
```

Use `await` to make Promises synchronous (blocking):
Expand Down
26 changes: 10 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,27 +180,21 @@ Now supposing you want to interact with the device, you have to consume its Thin
```JavaScript
// client.js
// Required steps to create a servient for a client
const { Servient, Helpers } = require("@node-wot/core");
const { Servient } = require("@node-wot/core");
const { HttpClientFactory } = require('@node-wot/binding-http');

const servient = new Servient();
servient.addClientFactory(new HttpClientFactory(null));
const WoTHelpers = new Helpers(servient);

WoTHelpers.fetch("http://localhost:8080/counter").then(async (td) => {
try {
const WoT = await servient.start();
// Then from here on you can consume the thing
let thing = await WoT.consume(td);
thing.observeProperty("count", async (data) => { console.log("count:", await data.value()); });
for (let i = 0; i < 5; i++) {
await thing.invokeAction("increment");
}
}
catch (err) {
console.error("Script error:", err);

servient.start().then(async (WoT) => {
const td = await WoT.requestThingDescription("http://localhost:8080/counter");
// Then from here on you can consume the thing
let thing = await WoT.consume(td);
thing.observeProperty("count", async (data) => { console.log("count:", await data.value()); });
for (let i = 0; i < 5; i++) {
await thing.invokeAction("increment");
}
JKRhb marked this conversation as resolved.
Show resolved Hide resolved
}).catch((err) => { console.error("Fetch error:", err); });
}).catch((err) => { console.error(err); });
```

If you execute both scripts you will see `count: ${count}` printed 5 times. We host a more complex version of this example at [http://plugfest.thingweb.io/examples/counter.html](http://plugfest.thingweb.io/examples/counter.html) and you can find the source code in the [counter example](./examples/browser) folder. You can also find more examples in the [examples folder](./examples/scripts) for JavaScript and in the [examples folder](./packages/examples/) for TypeScript. Finally, for your convenience, we host a set of online Things that you can use to test your applications. You can find more information about them in the [Online Things](#online-things) section.
Expand Down
3 changes: 1 addition & 2 deletions examples/scripts/counter-client.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,8 @@ function getFormIndexForDecrementWithCoAP(thing) {
// return formIndex: 0 if no CoAP target IRI found
return 0;
}
WoTHelpers.fetch("coap://localhost:5683/counter")
WoT.requestThingDescription("coap://localhost:5683/counter")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
try {
const thing = await WoT.consume(td);
console.info("=== TD ===");
Expand Down
3 changes: 1 addition & 2 deletions examples/scripts/smart-coffee-machine-client.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,14 @@
// This is an example of Web of Things consumer ("client" mode) Thing script.
// It considers a fictional smart coffee machine in order to demonstrate the capabilities of Web of Things.
// An accompanying tutorial is available at http://www.thingweb.io/smart-coffee-machine.html.

// Print data and an accompanying message in a distinguishable way
function log(msg, data) {
console.info("======================");
console.info(msg);
console.dir(data);
console.info("======================");
}
WoTHelpers.fetch("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
WoT.requestThingDescription("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
try {
const thing = await WoT.consume(td);
log("Thing Description:", td);
Expand Down
2 changes: 1 addition & 1 deletion examples/security/oauth/consumer.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
*
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/
WoTHelpers.fetch("https://localhost:8080/oauth").then((td) => {
WoT.requestThingDescription("https://localhost:8080/oauth").then((td) => {
WoT.consume(td).then(async (thing) => {
try {
const resp = await thing.invokeAction("sayOk");
Expand Down
3 changes: 1 addition & 2 deletions examples/testthing/testclient.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,9 +39,8 @@ async function testPropertyWrite(thing, name, value, shouldFail) {
else console.info("PASS " + name + " WRITE (" + displayValue + "):", JSON.stringify(err));
}
}
WoTHelpers.fetch("http://localhost:8080/testthing")
WoT.requestThingDescription("http://localhost:8080/testthing")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
try {
const thing = await WoT.consume(td);
console.info("=== TD ===");
Expand Down
14 changes: 6 additions & 8 deletions packages/binding-coap/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,18 @@ The Thing Description is located under the following CoAP URI `coap://plugfest.t

```js
// example-client.js
const { Servient, Helpers } = require("@node-wot/core");
const { Servient } = require("@node-wot/core");
const { CoapClientFactory } = require("@node-wot/binding-coap");

// create Servient and add CoAP binding
const servient = new Servient();
servient.addClientFactory(new CoapClientFactory());

const wotHelper = new Helpers(servient);
wotHelper
.fetch("coap://plugfest.thingweb.io:5683/testthing")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
servient
.start()
.then(async (WoT) => {
try {
const WoT = await servient.start();
const td = await WoT.requestThingDescription("coap://plugfest.thingweb.io:5683/testthing");
const thing = await WoT.consume(td);

// read property
Expand All @@ -50,7 +48,7 @@ wotHelper
}
})
.catch((err) => {
console.error("Fetch error:", err);
console.error("Start error:", err);
});
```

Expand Down
14 changes: 5 additions & 9 deletions packages/binding-http/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,15 @@ The Thing Description is located under the following uri <http://plugfest.thingw
Servient = require("@node-wot/core").Servient;
HttpClientFactory = require("@node-wot/binding-http").HttpClientFactory;

Helpers = require("@node-wot/core").Helpers;

// create Servient and add HTTP binding
let servient = new Servient();
servient.addClientFactory(new HttpClientFactory(null));

let wotHelper = new Helpers(servient);
wotHelper
.fetch("http://plugfest.thingweb.io:8083/testthing")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
servient
.start()
.then(async (WoT) => {
try {
const WoT = await servient.start();
const td = await WoT.requestThingDescription("http://plugfest.thingweb.io:8083/testthing");
const thing = await WoT.consume(td);

// read property
Expand All @@ -52,7 +48,7 @@ wotHelper
}
})
.catch((err) => {
console.error("Fetch error:", err);
console.error("Start error:", err);
});
```

Expand Down
16 changes: 6 additions & 10 deletions packages/examples/src/bindings/coap/example-client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,18 @@
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/

import { Servient, Helpers } from "@node-wot/core";
import { Servient } from "@node-wot/core";
import { CoapClientFactory } from "@node-wot/binding-coap";
import { ThingDescription } from "wot-typescript-definitions";

// create Servient and add CoAP binding
const servient = new Servient();
servient.addClientFactory(new CoapClientFactory());

const wotHelper = new Helpers(servient);
wotHelper
.fetch("coap://plugfest.thingweb.io:5683/testthing")
.then(async (fetched) => {
const td: ThingDescription = fetched as ThingDescription;
// using await for serial execution (note 'async' in then() of fetch())
servient
.start()
.then(async (WoT) => {
try {
const WoT = await servient.start();
const td = await WoT.requestThingDescription("coap://plugfest.thingweb.io:5683/testthing");
const thing = await WoT.consume(td);

// read property
Expand All @@ -39,5 +35,5 @@ wotHelper
}
})
.catch((err) => {
console.error("Fetch error:", err);
console.error("Start error:", err);
});
16 changes: 6 additions & 10 deletions packages/examples/src/bindings/http/example-client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,18 @@
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/

import { Servient, Helpers } from "@node-wot/core";
import { Servient } from "@node-wot/core";
import { HttpClientFactory } from "@node-wot/binding-http";
import { ThingDescription } from "wot-typescript-definitions";

// create Servient and add HTTP binding
const servient = new Servient();
servient.addClientFactory(new HttpClientFactory());

const wotHelper = new Helpers(servient);
wotHelper
.fetch("http://plugfest.thingweb.io:8083/testthing")
.then(async (fetched) => {
const td: ThingDescription = fetched as ThingDescription;
// using await for serial execution (note 'async' in then() of fetch())
servient
.start()
.then(async (WoT) => {
try {
const WoT = await servient.start();
const td = await WoT.requestThingDescription("http://plugfest.thingweb.io:8083/testthing");
const thing = await WoT.consume(td);

// read property
Expand All @@ -39,5 +35,5 @@ wotHelper
}
})
.catch((err) => {
console.error("Fetch error:", err);
console.error("Start error:", err);
});
10 changes: 2 additions & 8 deletions packages/examples/src/scripts/counter-client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,6 @@
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/

import { Helpers } from "@node-wot/core";
import { ThingDescription } from "wot-typescript-definitions";

let WoTHelpers!: Helpers;

function getFormIndexForDecrementWithCoAP(thing: WoT.ConsumedThing): number {
const forms = thing.getThingDescription().actions?.decrement.forms;
if (forms !== undefined) {
Expand All @@ -31,11 +26,10 @@ function getFormIndexForDecrementWithCoAP(thing: WoT.ConsumedThing): number {
return 0;
}

WoTHelpers.fetch("coap://localhost:5683/counter")
WoT.requestThingDescription("coap://localhost:5683/counter")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
try {
const thing = await WoT.consume(td as ThingDescription);
const thing = await WoT.consume(td);
console.info("=== TD ===");
console.info(td);
console.info("==========");
Expand Down
8 changes: 2 additions & 6 deletions packages/examples/src/scripts/smart-coffee-machine-client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,6 @@
// It considers a fictional smart coffee machine in order to demonstrate the capabilities of Web of Things.
// An accompanying tutorial is available at http://www.thingweb.io/smart-coffee-machine.html.

import { ThingDescription } from "wot-typescript-definitions";
import { Helpers } from "@node-wot/core";
let WoTHelpers!: Helpers;

// Print data and an accompanying message in a distinguishable way
function log(msg: string, data: unknown) {
console.info("======================");
Expand All @@ -29,9 +25,9 @@ function log(msg: string, data: unknown) {
console.info("======================");
}

WoTHelpers.fetch("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
WoT.requestThingDescription("http://127.0.0.1:8080/smart-coffee-machine").then(async (td) => {
try {
const thing = await WoT.consume(td as ThingDescription);
const thing = await WoT.consume(td);
log("Thing Description:", td);

// Read property allAvailableResources
Expand Down
8 changes: 2 additions & 6 deletions packages/examples/src/security/oauth/consumer.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,13 +12,9 @@
*
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/
import { Helpers } from "@node-wot/core";
import { ThingDescription } from "wot-typescript-definitions";

let WoTHelpers!: Helpers;

WoTHelpers.fetch("https://localhost:8080/oauth").then((td) => {
WoT.consume(td as ThingDescription).then(async (thing) => {
WoT.requestThingDescription("https://localhost:8080/oauth").then((td) => {
WoT.consume(td).then(async (thing) => {
try {
const resp = await thing.invokeAction("sayOk");
const result = await resp?.value();
Expand Down
9 changes: 2 additions & 7 deletions packages/examples/src/testthing/testclient.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,6 @@
* SPDX-License-Identifier: EPL-2.0 OR W3C-20150513
********************************************************************************/

import { Helpers } from "@node-wot/core";
import { ThingDescription } from "wot-typescript-definitions";
let WoTHelpers!: Helpers;

console.log = () => {
/* empty */
};
Expand Down Expand Up @@ -51,11 +47,10 @@ async function testPropertyWrite(
}
}

WoTHelpers.fetch("http://localhost:8080/testthing")
WoT.requestThingDescription("http://localhost:8080/testthing")
.then(async (td) => {
// using await for serial execution (note 'async' in then() of fetch())
try {
const thing = await WoT.consume(td as ThingDescription);
const thing = await WoT.consume(td);
console.info("=== TD ===");
console.info(td);
console.info("==========");
Expand Down
Loading