Tool to convert between the Matter data model and the Semantic Definition Format. The project is usable as a library or as a command line tool.
- Prerequisites
- Library installation and building
- Documentation
- Using the command line tool
- Using the library
- Mappings Overview
- License
As this software uses the std::unordered_map data type in combination with incomplete types, it has certain requirements for the compiler version.
- GCC >= 12.1
- Clang >= 15
- ESP-IDF >= 5.1
Note that the GCC and Clang versions are only provided since Ubuntu 24.04, otherwise you will have to install these versions yourself.
If you want to use the validation functionality, the library libxml2 has to be installed. For Ubuntu this can be done with:
sudo apt-get install libxml2-dev
Using CMake inside the sdf-matter-converter directory:
cmake .
cmake --build .
Before building, check that all prerequisites are fulfilled. Afterward you can use the command line tool.
The documentation for this software can be generated by using doxygen. For Linux this can be done inside the sdf-matter-converter directory with:
doxygen
On Windows this can be done by using a tool like Doxywizard
Run the converter with:
./sdf-matter-converter [flags]
Possible flags are:
| Parameter | Arguments | Default |
|---|---|---|
--matter-to-sdf |
- | False |
--sdf-to-matter |
- | False |
--roundtrip |
- | False |
-sdf-model |
Path to the sdf-model | - |
-sdf-mapping |
Path to the sdf-mapping | - |
-device-xml |
Path to the device type definition | - |
-cluster-xml |
Path to the cluster definition | - |
-validate |
Path to the schema (JSON or XSD) | - |
-o, -output |
Path for the output files | - |
-h, --help |
- |
The core library exposes two functions. One for converting SDF to the Matter data model and one for converting the Matter data model to SDF.
It is located in the lib\converter sub folder.
The documentation for the library can be generated by using the before mentioned generation process.
As examples for the Matter to SDF conversion, you can use the definitions inside data_model folder of the Matter repository. As examples for the SDF to Matter conversion, you can use the definitions inside sdfObject folder of the SDF Playground repository.
You can convert from Matter to SDF in the sdf-matter-converter directory with the following command:
./sdf-matter-converter --matter-to-sdf -device-xml <path_to_device_xml> -cluster-xml <path_to_cluster_xml_folder> -o "./converted.json"
You can convert from SDF to Matter in the sdf-matter-converter directory with the following command:
./sdf-matter-converter --sdf-to-matter -sdf-model <path_to_sdf_model> -sdf-mapping <path_to_sdf_mapping> -o "./converted.xml"
An SDF-Mapping needs to be given, but this can be an empty json file. Note that this will result in garbage ids for the Matter elements.
If you don't want to convert the files yourself, you can download the artifacts for the Matter to SDF or the SDF to Matter conversion for all files of the above repositories from the Actions Page.
| Matter | SDF |
|---|---|
| Node | SDF-Model |
| Device | sdfThing |
| Endpoint | sdfThing |
| Cluster | sdfObject |
| Attribute | sdfProperty |
| Command | sdfAction |
| Event | sdfEvent |
| Global Matter type | sdfData |
| SDF | Matter |
|---|---|
| sdfThing | Endpoint |
| sdfObject | Cluster |
| sdfProperty | Attribute |
| sdfAction | Command |
sdfInputData |
Client command data fields |
sdfOutputData |
Server command data fields |
| sdfEvent | Event |
sdfOutputData |
Event data field |
| sdfData | Matter data type |
This project is licensed under the Apache 2.0 license.