Skip to content

Commit

Permalink
refactor(td-tools): Aid updates (eclipse-thingweb#1107)
Browse files Browse the repository at this point in the history 
* fix(td-tools): use lowercase interaction names

e.g., "Properties" -> "properties"

* refactor: use AID submodel in examples (instead of AAS)

* refactor: move deprecated method to end of public methods

* Update packages/td-tools/src/util/README.md

Co-authored-by: Jan Romann <[email protected]>

* docs: improved wording based on feedback from @wiresio

---------

Co-authored-by: Jan Romann <[email protected]>
  • Loading branch information
@danielpeintner @JKRhb
danielpeintner and JKRhb authored Oct 11, 2023
1 parent 9557fe1 commit 1f71e3f
Show file tree
Hide file tree
Showing 6 changed files with 33 additions and 28 deletions.
23 changes: 14 additions & 9 deletions packages/td-tools/src/util/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,10 @@ The [IDTA Asset Interface Description (AID) working group](https://github.com/ad

#### AAS/AID to WoT TD

The file `counterHTTP.json` describes the counter sample in AID format for http binding. The `AssetInterfaceDescriptionUtil` utility class allows to transform the AID format to a valid WoT TD format which in the end can be properly consumed by node-wot.
The file `counterHTTP.json` describes the counter sample in AAS/AID format for http binding. The `AssetInterfaceDescriptionUtil` utility class allows to transform the AID format to a valid WoT TD format which in the end can be properly consumed by node-wot.

The example tries to load an AID file in AID format and transforms it to a regular WoT TD.
The example `aid-to-td.js` tries to transform an AID submodel (from an AAS file) into a regular WoT TD.
Note: Besides converting the AID submodel it is also possible to convert a full AAS file (see `transformTD2AAS(...)`).

```js
// aid-to-td.js
Expand All @@ -39,10 +40,13 @@ async function example() {
const aas = await fs.readFile("counterHTTP.json", {
encoding: "utf8",
});
// pick AID submodel
const aid = JSON.stringify(JSON.parse(aas).submodels[0]);

// transform AID to WoT TD
let tdAID = assetInterfaceDescriptionUtil.transformAAS2TD(aas, `{"title": "counter"}`);
// Note: transformAAS2TD() may have up to 3 input parameters
// * aas (required): AAS in JSON format
const tdAID = assetInterfaceDescriptionUtil.transformSM2TD(aid, `{"title": "counter"}`);
// Note: transformSM2TD() may have up to 3 input parameters
// * aid (required): AID submodel in JSON format
// * template (optional): Initial TD template
// * submodelRegex (optional): Submodel filter based on regular expression
// e.g., filtering HTTP only by calling transformAAS2TD(aas, `{}`, "HTTP")
Expand All @@ -65,7 +69,8 @@ example();

#### WoT TD to AAS/AID

The example tries to load online counter TD and converts it to AAS JSON format.
The example `td-to-aid.js` tries to load the online counter TD and converts it to an AID submodel in JSON format.
Note: Besides converting it into an AID submodel it is also possible to convert it into a full AAS form (see `transformTD2AAS(...)`).

```js
// td-to-aid.js
Expand All @@ -78,9 +83,9 @@ async function example() {
const response = await fetch("http://plugfest.thingweb.io:8083/counter");
const counterTD = await response.json();

const sm = assetInterfaceDescriptionUtil.transformTD2AAS(JSON.stringify(counterTD), ["http", "coap"]);
const sm = assetInterfaceDescriptionUtil.transformTD2SM(JSON.stringify(counterTD), ["http", "coap"]);

// print JSON format of AAS
// print JSON format of AID submodel
console.log(sm);
} catch (err) {
console.log(err);
Expand All @@ -98,4 +103,4 @@ example();
Note: make sure that the file `counterHTTP.json` is in the same folder as the script.

`node td-to-aid.js`
... will show the online counter im AAS/AID JSON format (usable by AASX Package Explorer 2023-08-01.alpha).
... will show the online counter im AAS/AID JSON format (compliant with AAS V3.0 and can be imported by AASX Package Explorer).
22 changes: 11 additions & 11 deletions packages/td-tools/src/util/asset-interface-description.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,11 +36,6 @@ const logError = debug(`${namespace}:error`);
*/

export class AssetInterfaceDescriptionUtil {
/** @deprecated use transformAAS2TD method instead */
public transformToTD(aid: string, template?: string, submodelRegex?: string): string {
return this.transformAAS2TD(aid, template, submodelRegex);
}

/**
* Transform AAS in JSON format to a WoT ThingDescription (TD)
*
Expand Down Expand Up @@ -188,6 +183,11 @@ export class AssetInterfaceDescriptionUtil {
return JSON.stringify(aidObject);
}

/** @deprecated use transformAAS2TD method instead */
public transformToTD(aid: string, template?: string, submodelRegex?: string): string {
return this.transformAAS2TD(aid, template, submodelRegex);
}

/*
* PRIVATE IMPLEMENTATION METHODS ARE FOLLOWING
*
Expand Down Expand Up @@ -454,7 +454,7 @@ export class AssetInterfaceDescriptionUtil {
logInfo("InterfaceMetadata");
if (smValue.value instanceof Array) {
for (const interactionValue of smValue.value) {
if (interactionValue.idShort === "Properties") {
if (interactionValue.idShort === "properties") {
if (interactionValue.value instanceof Array) {
for (const iValue of interactionValue.value) {
logInfo("Property: " + iValue.idShort);
Expand All @@ -468,7 +468,7 @@ export class AssetInterfaceDescriptionUtil {
smInformation.properties.get(iValue.idShort)?.push(propInter);
}
}
} else if (interactionValue.idShort === "Operations") {
} else if (interactionValue.idShort === "actions") {
if (interactionValue.value instanceof Array) {
for (const iValue of interactionValue.value) {
logInfo("Action: " + iValue.idShort);
Expand All @@ -482,7 +482,7 @@ export class AssetInterfaceDescriptionUtil {
smInformation.actions.get(iValue.idShort)?.push(actInter);
}
}
} else if (interactionValue.idShort === "Events") {
} else if (interactionValue.idShort === "events") {
if (interactionValue.value instanceof Array) {
for (const iValue of interactionValue.value) {
logInfo("Event: " + iValue.idShort);
Expand Down Expand Up @@ -898,19 +898,19 @@ export class AssetInterfaceDescriptionUtil {
const values: Array<unknown> = [];
// Properties
values.push({
idShort: "Properties",
idShort: "properties",
value: properties,
modelType: "SubmodelElementCollection",
});
// Actions
values.push({
idShort: "Actions",
idShort: "actions",
value: actions,
modelType: "SubmodelElementCollection",
});
// Events
values.push({
idShort: "Events",
idShort: "events",
value: events,
modelType: "SubmodelElementCollection",
});
Expand Down
4 changes: 2 additions & 2 deletions packages/td-tools/test/AssetInterfaceDescriptionTest.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,7 @@ class AssetInterfaceDescriptionUtilTest {
expect(smValue).to.have.property("value").to.be.an("array").to.have.lengthOf.greaterThan(0);
let hasProperties = false;
for (const interactionValues of smValue.value) {
if (interactionValues.idShort === "Properties") {
if (interactionValues.idShort === "properties") {
hasProperties = true;
expect(interactionValues)
.to.have.property("value")
Expand Down Expand Up @@ -439,7 +439,7 @@ class AssetInterfaceDescriptionUtilTest {
hasInterfaceMetadata = true;
expect(smValue).to.have.property("value").to.be.an("array").to.have.lengthOf.greaterThan(0);
for (const interactionValues of smValue.value) {
if (interactionValues.idShort === "Properties") {
if (interactionValues.idShort === "properties") {
expect(interactionValues).to.have.property("value").to.be.an("array").to.have.lengthOf(0);
}
}
Expand Down
Binary file modified packages/td-tools/test/util/counterHTTP.aasx
View file
Binary file not shown.
6 changes: 3 additions & 3 deletions packages/td-tools/test/util/counterHTTP.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@
"embeddedDataSpecifications": [],
"value": [
{
"idShort": "Properties",
"idShort": "properties",
"semanticId": {
"type": "ExternalReference",
"keys": []
Expand Down Expand Up @@ -473,7 +473,7 @@
"modelType": "SubmodelElementCollection"
},
{
"idShort": "Actions",
"idShort": "actions",
"semanticId": {
"type": "ExternalReference",
"keys": []
Expand All @@ -483,7 +483,7 @@
"modelType": "SubmodelElementCollection"
},
{
"idShort": "Events",
"idShort": "events",
"semanticId": {
"type": "ExternalReference",
"keys": []
Expand Down
6 changes: 3 additions & 3 deletions packages/td-tools/test/util/inverterModbus.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@
"idShort": "InterfaceMetadata",
"value": [
{
"idShort": "Properties",
"idShort": "properties",
"value": [
{
"idShort": "device_name",
Expand Down Expand Up @@ -144,12 +144,12 @@
"modelType": "SubmodelElementCollection"
},
{
"idShort": "Actions",
"idShort": "actions",
"value": [],
"modelType": "SubmodelElementCollection"
},
{
"idShort": "Events",
"idShort": "events",
"value": [],
"modelType": "SubmodelElementCollection"
}
Expand Down

0 comments on commit 1f71e3f

Please sign in to comment.