From 7d01cd0474ac57775dcdb491775ad8080b80fbaf Mon Sep 17 00:00:00 2001 From: Pedram Hadjian Date: Thu, 19 Oct 2023 15:20:48 +0200 Subject: [PATCH 1/4] First take on a possible cli workflow --- design/08-thing-model-catalog-workflow.md | 136 ++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 design/08-thing-model-catalog-workflow.md diff --git a/design/08-thing-model-catalog-workflow.md b/design/08-thing-model-catalog-workflow.md new file mode 100644 index 0000000..f6d2e2d --- /dev/null +++ b/design/08-thing-model-catalog-workflow.md @@ -0,0 +1,136 @@ +# Thing Model Catalog +## Worflow Description + +This design document proposes a user experience for the catalog interface derived from the design goals described in issue [#8]. + +### Consumption + +**Simple Search:** + +A user want to use the official Thing Model catalog and downloads the ```tm-catalog-cli``` to interact with it. running it without paramters yields: + +``` +Usage: + tm-catalog-cli [command] + +Available Commands: + add-repo + login + search + pull + push + index + validate + +Flags: + -h, --help help for tm-catalog-cli +``` + +The user wants to find a Thing Model for the Siemens PowerCenter 1000 data transceiver and tries the following: + +``` +> ./tm-catalog-cli search powercenter + +NAME DESCRIPTION STARS QUALITY +enrico/pc1000-7KN1110.tm.jsonld Well tested TM for Siemens PC1000 transceiver 40 Syn/Sem/Run/Man +siemens/7KN1110-0MC00.tm.jsonld PowerCenter1000 transceiver official Thing Model 10 Syn/Sem/Run/- +thomas/powercenter1000.tm.jsonld TM for the Siemens PowerCenter1000 3 Syn/-/-/- +``` + +The user now wants to pick the TM with the most stars and use it: + +``` +> ./tm-catalog-cli pull enrico/pc1000-7KN1110.jsonld +** Fetching enrico/pc1000-7KN1110.jsonld successful +``` + +and finds the file in the local directory. The user wants to find a TM for the arc fault detection device (AFDD) connected to the power center communication module, but the official catalog does not have a version available: + +``` +> ./tm-catalog-cli search afdd + +NAME DESCRIPTION STARS QUALITY + +``` + +The user now searches the catalog of his/her organization, but needs to login beforehand: + +``` +> ./tm-catalog-cli add-repo thing-catalog.siemens.com +** Login to thing-catalog.siemens.com successful +``` + +Running the search again yields a hit: + +``` +> ./tm-catalog-cli search afdd + +NAME DESCRIPTION STARS QUALITY +siemens/wot_AFDDEM.jsonld Official Thing Model for the AFDD module 20 Syn/Sem/Run/- +``` + +The user downloads it and starts using the Thing Model with their own WoT consumer + +``` +> ./tm-catalog-cli pull siemens/wot_AFDDEM.jsonld +** Fetching siemens/wot_AFDDEM.jsonld successful +``` + +**Custom Catalog:** + +The user has written some Thing Models for the current project, but they are not yet ready to be pushed to the companies or public catalogs. He/she wants to host them in a project-specific catalog. He creates a directory locally and imports his/her TMs: + +``` +> mkdir mycatalog; cd mycatalog +> tm-catalog-cli import ../thingmodels/*jsonld +** JSON Schema validation passed +** JSONLD Syntactic validation passed +** 1 Thing Model imported succesfully +** Index created + +> find . +doe/Siemens/3NACOM_FUSE/smartfuse.jsonld +catalog.index.1.json +``` + +To test the catalog locally, the user runs an http-server on the directory: +``` +> live-server . +Live server running on localhost port 8080 +``` + +Searching with the cli works: +``` +> tm-catalog-cli search --catalog-url=http://localhost:8080 "smart fuse" +NAME DESCRIPTION STARS QUALITY +Siemens/3NACOM_FUSE/smartfuse.jsonld WIP Thing Model for Siemens smart fuse 0 Syn/Sem/-/- +``` + +Now the user creates a git repository, adds all the files and pushes it to his/her github account at https://www.github.com/doe +``` +> git init . +> git add . +> git commit -m "inital commit of TMs for project valhalla" +> git push --set-upstream git@github.com:doe/mycatalog +``` + +The user then adds this new repository to the list of registered repositories with the following command: +``` +> tm-catalog-cli add-repo www.github.com:doe/mycatalog +** Registered catalog at https://raw.githubusercontent.com/doe/mycatalog +** Catalog contains 1 Thing Model +``` + +Running the search again without specifying the catalog URL works: +``` +> tm-catalog-cli search "smart fuse" +NAME DESCRIPTION STARS QUALITY +Siemens/3NACOM_FUSE/smartfuse.jsonld WIP Thing Model for Siemens smart fuse 0 Syn/Sem/-/- +``` + + + + + + +[#8]: https://github.com/web-of-things-open-source/proposal/issues/8 From 147d1ba39c19c1b20324add3312b46cae143d9ff Mon Sep 17 00:00:00 2001 From: Pedram Hadjian Date: Sun, 22 Oct 2023 22:56:28 +0200 Subject: [PATCH 2/4] consumer-workflow: changed wording from index to create-table --- design/08-thing-model-catalog-workflow.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/design/08-thing-model-catalog-workflow.md b/design/08-thing-model-catalog-workflow.md index f6d2e2d..9f5d08d 100644 --- a/design/08-thing-model-catalog-workflow.md +++ b/design/08-thing-model-catalog-workflow.md @@ -19,7 +19,7 @@ Available Commands: search pull push - index + create-table validate Flags: @@ -86,11 +86,11 @@ The user has written some Thing Models for the current project, but they are not ** JSON Schema validation passed ** JSONLD Syntactic validation passed ** 1 Thing Model imported succesfully -** Index created +** Table of Content created > find . doe/Siemens/3NACOM_FUSE/smartfuse.jsonld -catalog.index.1.json +catalog.toc.json ``` To test the catalog locally, the user runs an http-server on the directory: From aa59cca1cb1cb7fdcf51c64245bbdc9e35c38d71 Mon Sep 17 00:00:00 2001 From: Pedram Hadjian Date: Sun, 22 Oct 2023 23:19:25 +0200 Subject: [PATCH 3/4] consumer-workflow: changed verb from create-table to create-toc --- design/08-thing-model-catalog-workflow.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/design/08-thing-model-catalog-workflow.md b/design/08-thing-model-catalog-workflow.md index 9f5d08d..fe9d41f 100644 --- a/design/08-thing-model-catalog-workflow.md +++ b/design/08-thing-model-catalog-workflow.md @@ -19,7 +19,7 @@ Available Commands: search pull push - create-table + create-toc validate Flags: From 562c128b1cb53b9511dfb46ba9747e0d873c39ed Mon Sep 17 00:00:00 2001 From: hadjian Date: Wed, 22 Nov 2023 13:19:00 +0100 Subject: [PATCH 4/4] replaced command search with list for filtering the list --- design/08-thing-model-catalog-workflow.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/design/08-thing-model-catalog-workflow.md b/design/08-thing-model-catalog-workflow.md index fe9d41f..e98d378 100644 --- a/design/08-thing-model-catalog-workflow.md +++ b/design/08-thing-model-catalog-workflow.md @@ -16,6 +16,7 @@ Usage: Available Commands: add-repo login + list search pull push @@ -29,7 +30,7 @@ Flags: The user wants to find a Thing Model for the Siemens PowerCenter 1000 data transceiver and tries the following: ``` -> ./tm-catalog-cli search powercenter +> ./tm-catalog-cli list powercenter NAME DESCRIPTION STARS QUALITY enrico/pc1000-7KN1110.tm.jsonld Well tested TM for Siemens PC1000 transceiver 40 Syn/Sem/Run/Man @@ -40,14 +41,14 @@ thomas/powercenter1000.tm.jsonld TM for the Siemens PowerCenter1000 The user now wants to pick the TM with the most stars and use it: ``` -> ./tm-catalog-cli pull enrico/pc1000-7KN1110.jsonld +> ./tm-catalog-cli fetch enrico/pc1000-7KN1110.jsonld ** Fetching enrico/pc1000-7KN1110.jsonld successful ``` and finds the file in the local directory. The user wants to find a TM for the arc fault detection device (AFDD) connected to the power center communication module, but the official catalog does not have a version available: ``` -> ./tm-catalog-cli search afdd +> ./tm-catalog-cli list afdd NAME DESCRIPTION STARS QUALITY @@ -63,7 +64,7 @@ The user now searches the catalog of his/her organization, but needs to login be Running the search again yields a hit: ``` -> ./tm-catalog-cli search afdd +> ./tm-catalog-cli list afdd NAME DESCRIPTION STARS QUALITY siemens/wot_AFDDEM.jsonld Official Thing Model for the AFDD module 20 Syn/Sem/Run/- @@ -72,7 +73,7 @@ siemens/wot_AFDDEM.jsonld Official Thing Model for the AFDD module The user downloads it and starts using the Thing Model with their own WoT consumer ``` -> ./tm-catalog-cli pull siemens/wot_AFDDEM.jsonld +> ./tm-catalog-cli fetch siemens/wot_AFDDEM.jsonld ** Fetching siemens/wot_AFDDEM.jsonld successful ``` @@ -101,7 +102,7 @@ Live server running on localhost port 8080 Searching with the cli works: ``` -> tm-catalog-cli search --catalog-url=http://localhost:8080 "smart fuse" +> tm-catalog-cli list --catalog-url=http://localhost:8080 "smart fuse" NAME DESCRIPTION STARS QUALITY Siemens/3NACOM_FUSE/smartfuse.jsonld WIP Thing Model for Siemens smart fuse 0 Syn/Sem/-/- ``` @@ -123,7 +124,7 @@ The user then adds this new repository to the list of registered repositories wi Running the search again without specifying the catalog URL works: ``` -> tm-catalog-cli search "smart fuse" +> tm-catalog-cli list "smart fuse" NAME DESCRIPTION STARS QUALITY Siemens/3NACOM_FUSE/smartfuse.jsonld WIP Thing Model for Siemens smart fuse 0 Syn/Sem/-/- ```