SDTTool

Version 0.9

SDTTool is a utility to read and convert Smart Device Template (SDT) definitions.

Introduction

The Smart Device Template (SDT) schema defined by the Home Gateway Initiative (HGI) is a format to describe concrete and abstract devices as well as capabilities, data models and functions of those devices. See SDT Introduction and SDT Components for an introduction to the SDT.

SDTtool is a Python 3 script that reads SDT files and generates output in various formats. It can be used to produce documentation for the Devices and ModuleClasses of an SDT as well as to convert between different versions of the SDT.

Installation

Prerequisites

Python 3.x

An installation of Python 3 (version 3.5 or higher) is required. For an earlier version of Python (3.2 or higher) pathlib must be installed separately (see also PathLib).

Jinja2

SDTTool uses the template engine Jinja2. You need to install it, e.g. via pip:

pip install Jinja2

Copying

Download the latest release of SDTTool and copy them into a directory of your choice.

Usage

SDTTool is run as follows:

python3 sdttool.py -i anInputFile.xml 

This will read in the SDT version 2, the default, definitions from the file anInputFile.xml and writes the documentation in markdown format to standard out. Writing the output to a new file can be done like this:

python3 sdttool.py -i anInputFile.xml -o anOutputFile.md

To change the output format the option -of must be given:

python3 sdttool.py -i anInputFile.xml -o anOutputFile.opml -of opml

This would write the documentation in the OPML format to the file anOutputFile.opml.

The input format can be set by the option -if.

python3 sdttool.py -i anInputFile.xml -o anOutputFile.opml -of opml -if sdt2

It is also possible to generate Java interfaces and classes from SDT version 3 with the java output format. In this case the -o argument must point to an output directory.

python3 SDTTool.py -i anInputFile.xml -o anOutputDirectoy -of java

Skeletons of definitions and paths operations for a Swagger input file can be generated with the swagger output format. In this case the -o argument again must point to an output directory.

python3 SDTTool.py -i anInputFile.xml -o anOutputDirectoy -of swagger

Running the script without with the -h option or without any argument will present a an overview about all possible command line parameters.

Input Formats

• -if {sdt2,sdt3,sdt4} , --inputformat {sdt2,sdt3,sdt4}: The input format to read. The default is sdt4.

The following input formats are supported for the -if or --inputformat command line argument:

• sdt2: SDT Version 2.0.1
• sdt3: SDT Version 3.0
• sdt4: SDT Version 4.0, the default

Output Formats

Please note that not all output formats are available for every SDT version.

• -of {plain,opml,markdown,sdt3,sdt4,java,vorto-dsl,onem2m-svg,onem2m-xsd,swagger}, --outputformat {plain,opml,markdown,sdt3,sdt4,java,vorto-dsl,onem2m-svg,onem2m-xsd,swagger}: The output format for the result. The default is markdown.

Output formats for documentation for the -of or --outputformat command line argument:

• plain: This produces a plain text representation, with indentations, of the components of the input file.
• markdown: Markdown is a markup language with plain text formatting syntax designed so that it can be converted to many formats. GitHub natively supports markdown as its documentation format. See also the --markdowntablesargument below.
• opml: OPML (Outline Processor Markup Language) is a simple XML format for outlines, which can be imported in various mind mapping applications.
• sdt3: This output format is only valid when the input format is sdt2. It is used to convert SDT definitions from version 2 to version 3.
• java: This output format is only valid for the input format sdt3. It generates Java interfaces and classes for the input definition. For this output format the argument -o refers to an output directory, not a single file.
• vorto-dsl: This output format generates files that can be used to export Device, ModuleClass and data type definitions to an Eclipse Vorto repository. For this output format the argument -o refers to an output directory, not a single file.
• onem2m-svg: This output format generates SVG files that present the structure of Devices and ModuleClass in the graphical representation format used by oneM2M. For this output format the argument -o refers to an output directory, not a single file.
• onem2m-xsd: This output format generates XSD files according to the type definions of TS-0004 of the oneM2M specifications. For this output format the argument -o refers to an output directory, not a single file. The oneM2M domain needs to be specified via the --domain argument.
  In addition to the XSD files the following files are generated as well
  • Skeleton files for enum type definitions are generated in the hd sub-directory.
  • Files with newly found abbreviations (_Abbreviations.*). One file contains a python map, the other file contains the abbreviations in CSV format. Only new abbreviations, which are not found in the file that was specified with --abbreviationsinfile, are added.
• swagger: This output format generates YAML files with Swagger definitions for ModuleClasses and Devices. These files cannot be used directly, but provide the necessary Swagger definitions skeletons and paths operations that can be copied and adapted to a real Swagger definition.
  For this output format the argument -o refers to an output directory, not a single file.

Basic Arguments

• -i <filename>, --infile <filename>: Required argument. Specify the input file for the conversion.
• -o <filename>, --outfile <filename>: The output file or directory for the result. The default is stdout.

oneM2M specific arguments

• --domain <domain name>: Specify the domain name for XSD output.

• -ns <xsd prefix>, --namespaceprefix <xsd prefix>: Specify the XSD name space prefix for the model. This argument is mandatory when generating XSD and SVG drawings.

• --abbreviationsinfile <filename>: Specify the file that contains a CSV table of already existing abbreviations.

• --abbreviationlength <integer>: Specify the maximum length for abbreviations. The default is 5.

• --xsdtargetnamespace <URI> : Specify the target namespace for the oneM2M XSD.

• -mv <version number>, --modelversion <version number> : Specify the version of the model. This is used in the filenames of XSD and SVG files. "." characters are replaced with "_".

• --svg-with-attributes : Generate SVG drawings for ModuleClass attributes as well.

Markdown Specific Arguments

• --markdowntables: Generate tables instead of the usual list output style for markdown.
• --markdownpagebreak: Insert page breaks before ModuleClasse and Device definitions.

Other Arguments

• --hidedetails: Hide the details of module classes and devices when generating the documentation.
• -lf <filename>, --licensefile <filename>: Add the text of the specified file as a license to the generated files.

Configuration Files

Sometimes the number of command line arguments can get pretty big. Therefore, it is possible to put some or all arguments into a configuration file. This configuration file can be specified as follows

python3 SDTTool.py @config

It is also possible to have more than one configuration file:

python3 SDTTool.py @config1 @config2

or to mix command line arguments and configuration files:

python3 SDTTool.py @config --markdowntables

Limitations

• SDTTool does not validate the input XML. It is assumed that the input XML conforms to the SDT schema.
• Swagger support is not complete yet.

Changelog

See the Changelog for all changes.

Copyright and License

Copyright (c) 2015-2020 Deutsche Telekom AG

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.