generate-matter-wot-mapping.ts

// this script parses the Matter clusters from the JSON generated by generate-matter-clusters.ts
// and generates the mapping between Matter clusters and WoT TDs, adding ontologies verbs where possible.

import { readFileSync, writeFileSync } from "fs";
import {
  CLUSTERS_JSON_FILE_PATH,
  MATTER_WOT_MAPPING_FILE_PATH,
} from "./utils/environment.js";
import type {
  AttributeDataSchema,
  CommandDataSchema,
  MatterAvailableClusters,
  MatterClusterElement,
  MatterClusterId,
  MatterOntologiesMapping,
  MatterWotMapping,
} from "../../src/models";

/**
 * Some clusters mapped manually to **SAREF** ontology.
 * TODO: move to a separate file (e.g. a JSON file)
 */
const matterOntologiesMapping: MatterOntologiesMapping = {
  "6": {
    attributes: {
      0: {
        "@type": "saref:OnOffState",
      },
    },
    commands: {
      0: {
        "@type": "saref:OffCommand",
      },
      1: {
        "@type": "saref:OnCommand",
      },
      2: {
        "@type": "saref:ToggleCommand",
      },
    },
  },
  "8": {
    attributes: {
      0: {
        "@type": "saref:MultiLevelState",
      },
    },
    commands: {
      0: {
        "@type": "saref:SetLevelCommand",
      },
    },
  },
};

const parseAttribute = (
  clusterId: MatterClusterId,
  attribute: MatterClusterElement,
): AttributeDataSchema | undefined => {
  if (!attribute._attributes || !attribute._attributes.code) {
    return;
  }

  const code = parseInt(attribute._attributes.code, 16);

  const attributeOntologies =
    matterOntologiesMapping[clusterId]?.attributes?.[code] || {};

  // TODO: some attributes must not be exposed, because of security reasons, we need to handle them

  return {
    type: "integer",
    title: attribute._attributes?.define,
    description: attribute.description?._text,
    const: code,
    "@type": attributeOntologies["@type"],
  };
};

const parseCommand = (
  clusterId: MatterClusterId,
  command: MatterClusterElement,
): CommandDataSchema | undefined => {
  if (!command._attributes || !command._attributes.code) {
    return;
  }

  const code = parseInt(command._attributes.code, 16);

  const commandOntologies =
    matterOntologiesMapping[clusterId]?.commands?.[code] || {};

  // TODO: some commands must not be exposed, because of security reasons, we need to handle them

  const schema: CommandDataSchema = {
    type: "object",
    title: command._attributes.define,
    description: command.description?._text,
    "@type": commandOntologies["@type"],
    properties: {
      id: {
        type: "integer",
        const: code,
      },
    },
  };

  // if command has arguments, we add them to input schema at payload property, mapping arguments
  if (command.arg) {
    schema.properties!.payload = {
      type: "object",
      properties: {},
    };

    if (!Array.isArray(command.arg)) {
      command.arg = [command.arg];
    }

    for (const arg of command.arg) {
      if (!arg._attributes || !arg._attributes.name) {
        console.warn(
          `\tNo attribute for command: ${command._attributes.define} argument: ${arg}, skipping...`,
        );
        continue;
      }

      const name = arg._attributes.name;
      // TODO: we need map types in a better way and handle all matter-defined ones
      schema.properties!.payload.properties![name] = {
        type: "string",
        description: arg._attributes.type,
      };
    }
  }

  return schema;
};

export const main = () => {
  if (!CLUSTERS_JSON_FILE_PATH) {
    console.error("Invalid path to the clusters JSON file");
    return;
  }
  console.log("Clusters JSON file:", CLUSTERS_JSON_FILE_PATH);

  if (!MATTER_WOT_MAPPING_FILE_PATH) {
    console.error("Invalid path to the Matter WoT mapping file");
    return;
  }
  console.log("Matter WoT mapping file:", MATTER_WOT_MAPPING_FILE_PATH);

  const mapping: MatterWotMapping = {};

  const clusters: MatterAvailableClusters = JSON.parse(
    readFileSync(CLUSTERS_JSON_FILE_PATH, "utf8"),
  );
  for (const clusterId in clusters) {
    const cluster = clusters[clusterId as MatterClusterId];

    mapping[clusterId] = {
      properties: {
        [clusterId]: {
          title: cluster.name._text,
          description: cluster.description?._text,
          uriVariables: {
            attribute: {
              type: "integer",
              description: "Attrbute to read from the device",
              oneOf: [],
            },
          },
        },
      },
      actions: {
        [clusterId]: {
          title: cluster.name._text,
          description: cluster.description?._text,
          input: {
            type: "object",
            properties: {
              command: {
                type: "object",
                description: "Command to send to the device",
                oneOf: [],
              },
            },
          },
        },
      },
    };

    const tdProperties = mapping[clusterId].properties![clusterId];
    const tdActions = mapping[clusterId].actions![clusterId];

    if (cluster.attribute) {
      if (!Array.isArray(cluster.attribute)) {
        cluster.attribute = [cluster.attribute];
      }

      for (const attribute of cluster.attribute) {
        const parsedAttribute = parseAttribute(
          clusterId as MatterClusterId,
          attribute,
        );
        if (!parsedAttribute) {
          console.warn(
            `\tNo data for cluster: ${clusterId} attribute: ${attribute}, skipping...`,
          );
          continue;
        }

        tdProperties!.uriVariables!.attribute!.oneOf!.push(parsedAttribute);
      }
    }

    if (cluster.command) {
      if (!Array.isArray(cluster.command)) {
        cluster.command = [cluster.command];
      }

      for (const command of cluster.command) {
        const parsedCommand = parseCommand(
          clusterId as MatterClusterId,
          command,
        );
        if (!parsedCommand) {
          console.warn(
            `\tNo data for cluster: ${clusterId} command: ${command}, skipping...`,
          );
          continue;
        }

        tdActions!.input!.properties!.command!.oneOf!.push(parsedCommand);
      }
    }
  }

  // TODO: use @node-wot/td-tools to validate the generated TDs
  writeFileSync(MATTER_WOT_MAPPING_FILE_PATH, JSON.stringify(mapping, null, 2));

  console.log("Done!");
};

main();