ETS-Project parser

Parse an ETS-Project

Import the parser

import etsProjParser from './etsProjParser'

Initialize the parser

const retVal = await etsProjParser(pathToProjectFile, pathToWorkdir)

The initialization process mainly consists of the unpacking of the project
- ETS-Project files are simple ZIP files containing XML files
pathToProjectFile is the path of the ETS-Project file
pathToWorkdir is the path to the directory the project will be unpacked to
- The directory can be deleted after parsing is done - It should be deleted before parsing another project

Check if the initialization succeeded

If everything went fine, retVal will be the parser-function
On error, retVal will be an object of the Error type

if (retVal.constructor === Error) {
    console.error(retVal)
    process.exit(-1)
}

Start the actual parsing project

const result = await retVal(parseDeviceApplicationInformation)

parseDeviceApplicationInformation (Boolean) enables/disables parsing information about the applications running on KNX devices (See result.deviceApplicationLookupTable)
NOTE that it can take more than 30 seconds for bigger projects

Check if parsing the project succeeded

if (result.constructor === Error) {
    console.error(result)
}

The structure of a parsed project

result is the result returned from the parser
All the values below are example values

result = {
    projectInformation: {
        ID: "P-05A5",
        name: "ProjectXYZ",
        groupAddressStyle: "ThreeLevel",
        deviceCount: 33,
        lastModified: "1998-02-17T15:22:02.1918306Z",
        lastUsedPuid: 1234,
        GUID: "11c2cac3-4ab4-4548-8661-667a6c387cd9",
        completionStatus: "Editing",
        projectStart: "1996-06-18T22:22:42Z",
        etsVersion: {
            application: "ETS5",
            version: "5.4.953"
        }
    },
    topology: {
        areas: [
            ..., {
                ID: "P-05A5-0_A-1",
                name: "AreaABC",
                address: "1",
                lines: [
                    ..., {
                        ID: "P-05A5-0_L-1",
                        name: "Line123",
                        address: "1.0",
                        __referenceIDs: {
                            mediumTypeRefID: "MT-0"
                        },
                        devices: [
                            ..., {
                                ID: "P-05A5-0_DI-20",
                                name: "DeviceDEF",
                                description: "Is Green",
                                address: "1.0.13",
                                isCommunicationVisibilityCalculated: true,
                                programmingStatus: {
                                    serialNumber: "ABCDEFGH",
                                    applicationProgramLoaded: true,
                                    communicationPartLoaded: true,
                                    individualAddressLoaded: true,
                                    parametersLoaded: true,
                                    mediumConfigLoaded: true,
                                    lastUsedAPDULength: 40,
                                    maxReadAPDULength: 55,
                                    lastModified: "2009-01-24T20:25:11.7929688Z",
                                    lastDownload: "2010-12-24T22:30:00.7929688Z"
                                },
                                communicationObjectReferences: [
                                    ..., {
                                        __communicationObjectRefID: "M-0002_A-A062-11-180E_O-11_R-1426",
                                        description: "XYZ",
                                        readFlag: true,
                                        transmitFlag: false,
                                        updateFlag: true,
                                        writeFlag: true,
                                        isActive: true,
                                        channelID: "",
                                        connectors: [
                                            ..., {
                                                send: [
                                                    ..., {
                                                        __groupAddressRefID: "P-05A5-0_GA-17"
                                                    }, ...
                                                ],
                                                receive: [
                                                    ..., {
                                                        __groupAddressRefID: "P-05A5-0_GA-110"
                                                    }, ...
                                                ]
                                            }, ...
                                        ]
                                    }, ...
                                ],
                                parameterReferences: [
                                    ..., {
                                        __parameterRefID: "M-0002_A-A05C-32-3F16_P-24515_R-24515",
                                        parameterValue: "1"
                                    }, ...
                                ],
                                security: {
                                    sequenceNumber: 0,
                                    sequenceNumberTimestamp: "2011-02-29T18:03:03.0102982Z"
                                },
                                __referenceIDs: {
                                    productRefID: "M-0002_H-2CDG.20110.2011…CDG.20110.20113.20R0011",
                                    hardware2ProgramRefID: "M-0002_H-2CDG.20110.2011…R0011-1_HP-A05C-32-3F16"
                                }
                            }, ...
                        ]
                    }, ...
                ]
            }, ...
        ],
        unassignedDevices: [
            ..., contains the same type of objects as devices[], ...
        ]
    },
    buildings: [
        ..., {
            ID: "P-02A1-0_BP-1",
            name: "Building123",
            type: "Building",
            deviceReferences: [
                ..., {
                    __deviceRefID: "P-02A1-0_DI-1"
                }, ...
            ],
            functions: [
                ..., {
                    ID: "P-02A1-0_F-1",
                    name: "FunctionABC",
                    type: "SwitchableLight",
                    groupAddressReferences: [
                        ..., {
                            ID: "P-02A1-0_GF-5",
                            name: "GAReference123",
                            __groupAddressRefID: "P-02A1-0_GA-5"
                        }, ...
                    ]
                }, ...
            ],
            buildingParts: [
                ..., same type as the contents of buildings[] buf with another type, ...
            ]
        }, ...
    ],
    groupAddresses: {
        groupRanges: [
            ..., {
                ID: "P-02A1-0_GR-1",
                name: "New main group",
                rangeStart: 1,
                rangeEnd: 2047,
                passTroughLineCoupler: true,
                groupRanges: [
                    ..., GARanges can contain other GARanges, ...
                ],
                groupAddresses: [
                    ..., {
                        ID: "P-02A1-0_GA-1",
                        name: "GAName123",
                        address: 1,
                        description: "GroupAddressOfABC",
                        datapointType: "DPST-1-1",
                        passTroughLineCoupler: true,
                        centralFlag: false
                    }, ...
                ]
            }, ...
        ]
    },
    productLookupTable: [
        ..., {
            ID: "M-0002_H-2CDG.20110.20152.20R0011-1",
            name: "SA/S4.6.1.1",
            busCurrent: 12,
            serialNumber: "2CDG 110 152 R0011",
            flags: {
                isAccessory: false
                isPowerSupply: false
                isChoke: false
                isCoupler: false
                isPowerLineRepeater: false
                isPowerLineSignalFilter: false
                isCable: false
                isIPEnabled: false
                hasApplicationProgram1: true
                hasApplicationProgram2: false
                hasIndividualAddress: true
                noDownloadWithoutPlugin: false
            },
            products: [
                ..., {
                    ID: "M-0002_H-2CDG.20110.20152.20R0011-1_P-2CDG.20110.20152.20R0011",
                    text: "SA/S4.6.1.1 Switch Actuator,4-fold,6A,MDRC",
                    orderNumber: "2CDG 110 152 R0011",
                    visibleDescription: "ProductDescriptionABC"
                }, ...
            ],
            __referenceIDs: {
                originalManufacturerID: "M-00C5",
                manufacturerID: "M-00C8",
                applicationProgramRefID: "M-0083_A-000D-11-501B"
            }
        }, ...
    ],
    manufacturerLookupTable: [
        ..., {
            ID: "M-0001",
            KNXmanufacturerID: "1",
            manufacturerName: "Siemens"
        }, ...
    ],
    datapointLookupTable: [
        ..., {
            ID: "DPT-1",
            dptNumber: 1,
            dptName: "1.xxx",
            dptText: "1-bit",
            dptSizeInBit: 1,
            datapointSubtypes: [
                ..., {
                    ID: "DPST-1-1",
                    subDptNumber: 1,
                    subDptName: "DPT_Switch",
                    subDptText: "switch"
                }, ...
            ]
        }, ...
    ],
    mediumTypeLookupTable: [
        ..., {
            ID: "MT-1",
            number: 1,
            name: "PL",
            text: "PowerLine",
            domainAddressLength: 8
        }, ...
    ],
    deviceApplicationLookupTable: [
        ..., {
            ID: "M-0002_A-A088-32-C0B5",
            name: "Switch 4f 6A/3.2b",
            number: 41096,
            version: "50",
            programType: "ApplicationProgram",
            maskVersion: "MV-0701",
            __manufacturerRefID: "M-0002"
        }, ...
    ],
    deviceMaskversionLookupTable: [
        ..., {
            ID: "MV-0010",
            maskVersion: 16,
            managementModel: "Bcu1",
            unloadedIndividualAddress: 65280,
            maxIndividualAddress: 32767,
            maxGroupAddress: 4095,
            __mediumTypeRefID: "MT-0",
            __otherMediumTypeRefID: "MT-1",
            resources: [
                ..., {
                    name: "ManagementStyle",
                    access: "remote local1",
                    addressSpace: "StandardMemory",
                    startAddress: 1,
                    ptrResource: "GroupObjectTablePtr",
                    interfaceObjectRef: 2,
                    propertyID: 5,
                    occurrence: 1,
                    length: 2,
                    flavour: "GroupObjectTable_Bcu11",
                    readRights: "Runtime",
                    writeRights: "Configuration"
                }, ...
            ],
            compatibleMaskVersionIDs: [
                ..., "MV-0910", ...
            ]
        }, ...
    ],
    // Functions
    getProjectInformation: Function,
    getAreas: Function,
    getAreaByKey: Function,
    getLines: Function,
    getLineByKey: Function,
    getUnassignedDevices: Function,
    getUnassignedDeviceByKey: Function,
    getDevices: Function,
    getDeviceByKey: Function,
    getBuildingParts: Function,
    getBuildingPartByKey: Function,
    getFunctions: Function,
    getFunctionByKey: Function,
    getGroupAddresses: Function,
    getGroupAddressByKey: Function,
    getProductsFamilies: Function,
    getProductFamilyByKey: Function,
    getProducts: Function,
    getProductByKey: Function,
    getManufacturers: Function,
    getManufacturerByKey: Function,
    getDatapointTypes: Function,
    getDatapointTypeByKey: Function,
    getDatapointSubTypes: Function,
    getDatapointSubTypeByKey: Function,
    getMediumTypes: Function,
    gedMediumTypeByKey: Function,
    getDeviceApplicationInformation: Function,
    getDeviceApplicationInformationByKey: Function,
    getMaskversions: Function,
    getMaskversionByKey: Function,
    exportToJson: Function
}

The parts of a parsed project

Single objects of the structure (above) are explained here
Some objects lack explanation, due to missing information
Normally, a whole tree is contained in one section below. But there are some exceptions, like the topology tree, that are split up because they are to complex for one section

`result.projectInformation`

It contains general information about the project parsed from the project information file
- This file is contained in the project directory inside the unpacked project:
```
path/to/unpacked/project/P-*/project.xml
```
- .ID stores the id of the project (String). Same name as the project directory inside the unpacked project. Normal format:
```
"P-####"        Where '#' is replaced with other characters or numbers
```
- .name stores the name of the project. (String)
- .groupAddressStyle stores the group address representation style used in the project (String). Possible values:
```
"Free"          No preferred group address representation is set        (both x/y and x/y/z)
"TwoLevel"      Group addresses are represented in two-level-style      (only x/y)
"ThreeLevel"    Group addresses are represented in three-level-style    (only x/y/z)
```
- .deviceCount stores the number of devices contained in the project (Number)
- .lastModified stores a date string representing the date the project was last modified (String)
- .lastUsedPUID ... (Number)
- .GUID ... (String)
- .completionStatus stores the completion status of the project (String). Possible values:
```
"FinishedDesign"
"Locked"
"Accepted"
"Tested"
"FinishedCommissioning"
"Editing"
"Unknown"
```
- .projectStart stores a date string representing the starting date of the project (String)
- .etsVersion stores information about the used version of ETS
  - .application store the name of the used application (String). Normally one of:
```
"ETS5"          For all variations of ETS five
"ETS4"          For all variations of ETS four
```
  - .version stores the more precise sub-version of the ETS version used (String)

`result.topology`

It contains the project topology which contains all areas, lines and devices with their attributes stored in relation to each other
.areas[] stores information about all areas contained in the project

`result.topology.unassignedDevices[]`

It contains devices that aren't designated to any area (and line)
The device objects contained in it are the same as those in result.topology.areas[n].lines[n1].devices[] (see below)

`result.topology.areas[]`

(Described below is a single element of result.topology.areas[])
.ID stores the ID of the area (String). Normally like:
```
"[PROJECT_ID]-n_A-x"
```
- [PROJECT_ID] is the ID of the project (see result.projectInformation.ID)
- n some number
- A stands for "Area"
- x is the area index, starting for one
.name stores the name of the area (String)
.address stores the ares part of the individual address of a device (String)
```
"AA.LL.DDD"
```
- AA is the area part
- < 4²
.lines[] stores all line contained in the area

`result.topology.areas[n].lines[]`

(Described below is a single element of result.topology.areas[n].lines[])
.ID stores the ID of the line (String). Normally like:
```
"[PROJECT_ID]-n_L-x"
```
- [PROJECT_ID] is the ID of the project (see projectInformation.ID)
- n some number
- L stands for "Line"
- x is the line index, starting for one
.name store the name of the line (String)
.address stores the area and the line part of the individual address of a device (String)
```
"AA.LL.DDD"
```
- LL is the line part
- < 4²
.__referenceIDs contains IDs referencing other objects
- .mediumTypeRefID stores the reference ID of the used physical medium (String). Can be resolved using:
```
result.getMediumTypeByKey('ID', .mediumTypeRefID)
```
.devices[] stores all devices contained in the line

`result.topology.areas[n].lines[n1].devices[]`

(Described below is a single element of result.topology.areas[n].lines[n1].devices[])
.ID stores the ID of the device (String). Normally like:
```
"[PROJECT_ID]-n_DI-x"
```
- [PROJECT_ID] is the ID of the project (see projectInformation.ID)
- n some number
- DI stands for "Device" (forget about the I)
- x is the device index
.address stores the whole individual address of a device (String)
```
"AA.LL.DDD"
```
- DDD is the device part
- < 8²
.isCommunicationVisibilityCalculated ...

.programmingStatus stores device-programming related information

.serialNumber Stores the serial number of the device (String)
.applicationProgramLoaded (Boolean) Possible values:

true        The application program is loaded onto the device
false       The application program is not loaded onto the device

.communicationPartLoaded (Boolean) Possible values:

true        The communication part is loaded onto the device
false       The communication part is not loaded onto the device

.individualAddressLoaded (Boolean) Possible values:

true        The individual address is loaded onto the device
false       The individual address is not loaded onto the device

.parametersLoaded (Boolean) Possible values:

true        The application parameters are loaded onto the device
false       The application parameters are not loaded onto the device

.mediumConfigLoaded (Boolean) Possible values:

true        The medium config is loaded onto the device
false       The medium config is not loaded onto the device

.lastUsedAPDULength (Number) ...
.maxReadAPDULength (Number) ...
.lastModified (String) stores the date of the last time the devices programming was changed
.lastDownload (String) stores the data of the last time something was written to the device

.security ...
- .sequenceNumber (Number)
- .sequenceNumberTimestamp (String) stores the date of the origin of the sequenceNumber
.__referenceIDs
- .productRefID (String) stores the reference to the product/hardware this device is. Can be resolved with:
```
result.getProductByKey('ID', .productRefID)
```
- .hardware2ProgramRefID (String) stores the reference to the application running on this device
.parameterReferences[] explained below
.communicationObjectReferences[] explained below

`result.topology.areas[n].lines[n1].devices[n2].parameterReferences[]`

(Described below is a single element of result.topology.areas[n].lines[n1].devices[n2].parameterReferences[])
It stores information about device parameters/settings
.__parameterRefID (String) stores the ID of the referenced parameter
- No parameter reference resolving supported
.parameterValue stores the value of the referenced parameter
- No static type can be determined

`result.topology.areas[n].lines[n1].devices[n2].communicationObjectReferences[]`

(Described below is a single element of result.topology.areas[n].lines[n1].devices[n2].communicationObjectReferences[])
A communication object is an object that describes how and with whom the device communicates linked to a specific property of the device
It also contains the group addresses used and the read, transmit and update flag of the property
It is the data behind 'Group Objects' tab of a device in ETS
.__communicationObjectRefID (String) stores the ID of the referenced communication object
.description (String) stores the description
.readFlag (Boolean) if the object is readable or noht
.transmitFlag (Boolean) if the object is transmittable (?) or not
.updateFlag (Boolean) if the object is updateable (?) or not
.writeFlag (Boolean) if the object is writable or not
.isActive (Boolean) if the object is active or not
.channelID (Unknown) ...
.connectors stores information about where data is sent to and where data will be received from
- .send[] stores group addresses to which data will be sent to
  - .__groupAddressRefID (String) stores the ID of the referenced group address
- receive[] stores group addresses from which data will be received
  - .__groupAddressRedID (String) stores the ID of the referenced group address

`result.buildings[]`

(Described below is a single element of result.buildings[])
It contains all buildings, building parts, devices and functions of the project stored in relation to each other
It is important to notice that a building is technically a building part like a floor, a stairway, ...
.ID (String) stores the ID of the building part
```
"[PROJECT_ID]-n_BP-x"
```
- [PROJECT_ID] is the ID of the project (see projectInformation.ID)
- n some number
- BP stands for BuildingPart
- x is the buildings index
.name (String) the name of the building part

.type (String) the type of the building part. Normally one of:

"Building"
"BuildingPart"
"Room"
"DistributionBoard"
"Floor"
"Stairway"

.deviceReferences[]
- .__deviceRefID (String) stores the ID of the referenced device. Can be resolved with:
```
result.getDeviceByKey('ID', .__deviceRefID)
```
.functions[]
- .ID (String) the ID of the function
```
"[PROJECT_ID]-n_F-x"
```
  - [PROJECT_ID] is the ID of the project (see projectInformation.ID)
  - n some number
  - F stands for Function
  - x is the functions index
- .name (String) stores the name of the function
- .type (String) stores the type of the function. Normally one of:
```
"DimmableLight"
"SwitchableLight"
"SunProtection"
"HeatingRadiator"
"HeatingFloor"
"Custom"
```
- .groupAddressReferences[]
  - .ID (String) stores the ID of the group address reference
```
"P-02A1-0_GF-5"
```
  - .name (String) stores the name of the GAF
  - .role (String) stores the role of the GAF. Examples:
```
"SwitchOnOff"
"RelativeSetvalueControl"
"ActualDimmingValue"
"InfoOnOff"
```
  - .__groupAddressRefID (String) stores the ID of the referenced GroupAddress. Can be resolved with:
```
result.getGroupAddressByKey('ID', .__groupAddressRefID)
```
.buildingParts[] stores more building parts ("recursive")

`result.groupAddresses[]`

(Described below is a single element of result.groupAddresses[])
Contains a structure of GroupRanges which contain GroupAddresses
.groupRanges[]
.ID (String) stores the ID of the GroupRange
```
"[PROJECT_ID]-n_GR-x"
```
- [PROJECT_ID] is the ID of the project (see projectInformation.ID)
- n some number
- GR stands for GroupRange
- x is the group ranges index
.name (String) stores the name of the GroupRange
.rangeStart (Number) stores the start group address of the range
.rangeEnd (Number) stores the end group address of the range

.passTroughLineCoupler (Boolean) Possible values:

true        Messages with group addresses in this range will be passed trough a line coupler
false       Messages with group addresses in this range won't be passed trough a line coupler

.groupAddresses[]
- .ID (String) stores the ID of the GroupAddress
```
"[PROJECT_ID]-n_GA-x"
```
  - [PROJECT_ID] is the ID of the project (see projectInformation.ID)
  - n some number
  - GA stands for GroupAddress
  - x is the group addresses index
- .name (String) stores the name of the GroupAddress
- .address (Number) stores the actual GroupAddress
- .description (String) stores the description of the GroupAddress
- .datapointType (String) stores the datapoint type ID associated with this address.
  - There are two possible .datapointType "variations":
```
DPT-n
DPST-n-n1
```
  - DP(S)T stands for Datapoint(Sub)Type
  - n is the number of the datapoint type
  - n1 is the number of the datapoint sub-type
```
result.getDatapointTypeByKey('ID', .datapointType)
```
  - The first variation can be resolved with:
```
result.getDatapointType('ID', .datapointType)
```
  - ... and the second one can be resolved with:
```
result.getDatapointSubTypeByKey('ID', .datapointType)
```
- .passTroughLineCoupler (Boolean) Possible values:
```
true        Messages with group addresses in this range will be passed trough a line coupler
false       Messages with group addresses in this range won't be passed trough a line coupler
```
  - If .passTroughLineCoupler is set in the GroupRange above, it is inherited from it
- .centralFlag (Boolean) ...

`result.productLookupTable[]`

(Described below is a single element of result.productLookupTable[])
It contains product families containing products
.ID (String) stores the ID of the product family
```
"[MANUFACTURER_ID]_[PRODUCT/MANUFACTURER_SPECIFIC]"
Example:   "M-0002_H-2CDG.20110.20152.20R0011-1"
```
- For information about MANUFACTURER_IDs, see result.manufacturerLookupTable[]
.name (String) stores the name of the product family
.busCurrent (Number) ...
.serialNumber (String) stores the serial number of the product family
.flags
- .isAccessory (Boolean)
- .isPowerSupply (Boolean)
- .isChoke (Boolean)
- .isCoupler (Boolean)
- .isPowerLineRepeater (Boolean)
- .isPowerLineSignalFilter (Boolean)
- .isCable (Boolean)
- .isIPEnabled (Boolean)
- .hasApplicationProgram1 (Boolean)
- .hasApplicationProgram2 (Boolean)
- .hasIndividualAddress (Boolean)
- .noDownloadWithoutPlugin (Boolean) One of:
```
true        All devices in this family can't be programmed without using a manufacturer specific plugin
false       All devices in this family can be programmed the normal way
```
.products[] Contains the actual products contained in the product family
- .ID (String) stores the ID of the product
  - Same structure as the .ID field of the overlaying product family, but with more data appended to it
- .text (String) stores a short name-like description of the product
- .orderNumber (String) ...
- .visibleDescription (String) stores a description of the product
.__referenceIDs[]
- .originalManufacturerID (String) stores the ID of the manufacturer who originally produced this product
- .manufacturerID (String) stores the ID of the manufacturer who sold this product
- .applicationProgramRefID (String) the ID of the application program used for this product family
- .originalManufacturerID and .manufacturerID can be resolved with:
```
result.getManufacturerByKey('ID', .originalManufacturerID or .manufacturerID)
```
- .applicationProgramRefID can be resolved with:
```
result.getDeviceApplicationInformationByKey('ID', .applicationProgramRefID)
```

`result.manufacturerLookupTable[]`

(Described below is a single element of result.manufacturerLookupTable[])
It contains information about KNX device manufacturers
.ID (String) stores the ID of the manufacturer
```
"M-0001"
```
- M standing for "Manufacturer"
- 0001 being the manufacturer ID, this one standing for Siemens
.KNXmanufacturerID (Number) being the KNX manufacturer number/ID
.manufacturerName (String) stores the name of the manufacturer

`result.datapointLookupTable[]`

(Described below is a single element of result.datapointLookupTable[])
It contains information about datapoint types and their sub-types
.ID (String) stores the ID of the datapoint type
```
"DPT-1"
```
- DPT stands for "DataPointType"
- 1 is the ID/number of the DPT
.dptNumber (Number) stores the number of this DPT
.dptName (String) stores the name of this DPT
.dptText (String) stores a short describing string about this DPT
.dptSizeInBit (Number) stores the size of the data transmitted labeled with this DPT
.datapointSubtypes
- .ID (String) stores the ID of the datapoint sub-type
```
"DPST-1-1"
```
  - DPST stand for DataPointSubType
  - 1 is the ID/number of the DPT
  - 1 is the ID/number of the DPST
- .subDptNumber (Number) stores the number of the DPST
- .subDptName (String) stores the name of the DPST
- .subDptText (String) stores a short describing string about this DPST

`result.mediumTypeLookupTable[]`

(Described below is a single element of result.mediumTypeLookupTable[])
It contains information about physical KNX mediums
.ID (String) stores the ID of the KNX medium
```
"MT-1"
```
- MT stands for MediumType
- 1 is the MT number
.number (Number) stores the number of the MT
.name (String) stores the name of the MT
.text (String) stores a short describing string about this MT
.domainAddressLength (Number) ...

`result.deviceApplicationLookupTable`

(Described below is a single element of result.deviceApplicationLookupTable)
It contains information about device application programs
.ID (String) stores the ID of the device application program
.name (String) stores the name of the DAP
.number (Number) stores the DAP number (also stored on the KNX device)
.version (String) stores the version of the DAP (-||-)
.programType (String) stores a string describing the type of the DAP. Possible values:
```
...
```
.maskVersion (String) stores the mask version for the application program
.__manufacturerRefID (String) stores the ID of the manufacturer of the device family this application program should run on. Can be resolved with:
```
result.getManufacturerByKey('ID', .__manufacturerRefID)
```

`result.deviceMaskversionLookupTable`

(Described below is a single element of result.deviceMaskversionLookupTable)
```
"MV-0010"
```
- MV stand for MaskVersion
- 0010 represents the maskversion number in hex (see .maskVersion)
.ID (String) stores the ID of the device maskversion
.name (String) stores the name of the maskversion
.maskVersion (Number) the number of the maskversion
.managementModel (String) stores the management model of this maskversion. Some examples:
```
"None"
"Bcu1"
"Bcu2"
"PropertyBased"
"BimM112"
"SystemB"
```
.unloadedIndividualAddress (Number) stores the individual address the device would use when it isn't programmed to use another address
.maxIndividualAddress (Number) stores the highest individual address usable with devices (device applications) with this maskversion
.maxGroupAddress (Number) stores the highest group address usable with devices (device applications) with this maskversion
.__mediumTypeRefID (String) stores the reference ID of the medium type device applications with this maskversion can run on
.__otherMediumTypeRefIDs (String) stores a reference ID of an alternative medium type
.compatibleMaskVersionIDs[] (String[]) stores strings (like .__mediumTypeRefID)
.resources[]

`result.deviceMaskversionLookupTable.resources`

(Described below is a single element of result.deviceMaskversionLookupTable.resources)

A resource describes a resource available on KNX devices with the corresponding maskversion
- Normally, the resource is a value than can be read/written from/to the device like the ProgrammingMode resource, which can be read to check if the device is in programming mode. It can also be set into programming mode by writing a value to the resource
- There are (mostly) two ways of accessing a resource:
  - Via direct memory reading/writing - for this .startAddress, .length and .addressSpace must be given
  - Via property read/write requests - for this .propertyID, .length
.name (String) stores the name of the resource
.access (String) stores a string describing how/from where the resource is accessible. Examples:
```
"remote local1"
"remote local2"
"local1"
"remote local1 local2"
```

.addressSpace (String) stores a string describing describing in which address space the resource is stored on the KNX device. Normally one of:

"SystemProperty"
"StandardMemory"
"RelativeMemory"
"RelativeMemoryByObjectType"
"Pointer"
"Property"
"LcFilterMemory"
"Constant"
"ADC"
"None"

.startAddress (Number) stores the address of the first byte to read when using direct memory access
.ptrResource (String) stores the name of the resource that points to this resource
- Will only be set if .addressSpace equals
```
"Pointer"
```
- Usually one of:
```
"GroupAddressTablePtr"
"GroupAssociationTablePtr"
"GroupObjectTablePtr"
```
.interfaceObjectRef (Number) ...
.propertyID (Number)
.occurrence (Number) stores the property ID when using property based access
.length (Number) stores the length of the resource, independent from the method used to access the resource

.flavour (String) stores the flavour/type of the resource. (Usually) one of:

"AddressTable_Bcu1",
"AddressTable_Bcu1PL",
"AddressTable_SystemB"
"AssociationTable_Bcu1"
"AssociationTable_Bcu2"
"AssociationTable_M112"
"AssociationTable_SysteB"
"FrequencyChannel_Bcu1PL"
"GroupObjectTable_Bcu10"
"GroupObjectTable_Bcu11"
"GroupObjectTable_Bcu1PL"
"GroupObjectTable_Bcu2"
"GroupObjectTable_M112"
"GroupObjectTable_System300"
"GroupObjectTable_SystemB"
"HardwareConfig_Identical"
"HardwareConfig_Version"
"Lc_10"
"Lc_11"
"Lc_12"
"LoadControl_Bcu2"
"LoadControl_M112"
"ManagementStyle_Bcu2"
"PeiType_Adc"
"PeiType_Prop"
"PlMc"
"ProgrammingMode_Bcu1"
"ProgrammingMode_Prop"
"Ptr_StandardMemory"
"Ptr_StandardMemory100"
"ReConfig_Bcu1PL"
"ReConfig_Rf"
"RunControl_Bcu1"
"Runerror_Bcu1"
"Sensitivity_Bcu1PL"
"Stamp_SystemB"
"Voltage_Adc"

.readRights (String) stores a string describing the "situation" in which the resource can be read. Examples:
```
"Configuration"
"None"
"Runtime"
```
.writeRights (String) stores a string describing the "situation" in which the resource can be written. Examples:
```
"Configuration"
"None"
"Runtime"
```

Functions

For information on the returned values, see above

`result.get*ByKey(key, value)`

Function of this type (see below) are used to get an element which matches the key-value pair

let a = [
    {
        b: 1,
        c: 2,
        e: 5
    },
    {
        b: { c: 3 },
        e: 5
    },
    {
        d: 4,
        e: 5
    }
]

// If there would be a function result.getAByKey()
//      result.getAByKey('b', 1) would return [{b: 1, c: 2, e: 5}]
//      result.getAByKey(['b', 'c'], 3) would return [{b: { c: 3 }, e: 5}]
//      result.getAByKey('e', 5) would return all members of the array a

`result.getProjectInformation()`

Returns result.projectInformation

`result.getAreas()`

Returns result.topology.areas[]

`result.getAreaByKey(key, value)`

Returns an array of matching elements of result.topology.areas[]

`result.getLines()`

Returns result.topology.areas[n].lines[]

`result.getLineByKey(key, value)`

Returns an array of matching elements of result.topology.areas[n].lines[]

`result.getUnassignedDevices()`

Returns result.topology.unassignedDevices[]

`result.getUnassignedDeviceByKey(key, value)`

Returns an array of matching elements of result.topology.unassignedDevices[]

`result.getDevices()`

Returns result.topology.areas[n].lines[n1].devices[]

`result.getDeviceByKey(key, value)`

Returns an array of matching elements of result.topology.areas[n].lines[n1].devices[]

`result.getBuildingParts()`

Returns result.buildings[]

`result.getBuildingPartByKey(key, value)`

Returns an array of matching elements of result.buildings[]

`result.getFunctions()`

Returns result.buildings[n].functions[]

`result.getFunctionByKey(key, value)`

Return an array of matching elements of result.buildings[n].functions[]

`result.getGroupAddresses()`

Returns result.groupAddresses[]

`result.getGroupAddressByKey(key, value)`

Returns an array matching elements of result.groupAddresses[0-n].groupAddresses[]

`result.getProductFamilies()`

Returns result.productLookupTable[]

`result.getProductFamilyByKey(key, value)`

Returns an array of matching elements of result.productLookupTable[]

`result.getProducts()`

Returns result.productLookupTable[n].products[] with a modification:
- Every product contained in the returned array got an extra field:
```
result.productLookupTable[n].products[n1].productFamilyInformation
```
  - which represents the result.productLookupTable[n] object the product was originally contained in
  - NOTE that the .products field of the .productFamilyInformation field is deleted

`result.getProductByKey(key, value)`

Returns result.productLookupTable[n].products
- All elements are altered as described above (result.getProducts())

`result.getManufacturers()`

Returns result.manufacturerLookupTable[]

`result.getManufacturerByKey(key, value)`

Returns an array of matching elements of result.manufacturerLookupTable[]

`result.getDatapointTypes()`

Returns result.datapointLookupTable[]

`result.getDatapointTypeByKey(key, value)`

Returns an array of matching elements of result.datapointLookupTable[]

`result.getDatapointSubTypes()`

Returns result.datapointLookupTable[n].datapointSubtypes[]

`result.getDatapointSubTypeByKey(key, value)`

Returns an array of matching elements of result.datapointLookupTable[n].datapointSubtypes[]

`result.getMediumTypes()`

Returns result.mediumTypeLookupTable[]

`result.getMediumTypeByKey(key, value)`

Returns an array of matching elements of result.mediumTypeLookupTable[]

`result.getDeviceApplicationInformation()`

Returns result.deviceApplicationLookupTable

`result.getDeviceApplicationInformationByKey(key, value)`

Returns an array of matching elements of result.deviceApplicationLookupTable

`result.exportToJson(outputFilePath)`

Writes the parsed project (result) into outputFilePath in JSON format
Functions are obviously not written into that file

Import a parsed project

An exported parsed project (in JSON format) can be imported like this:

import readProject from './readProjectFromJson'

let result = await readProject(pathToExportedParsedProject).catch(e => {
    ...
})

pathToExportedParsedProject is a path a parsed exported project (a file written by result.exportToJson())
The returned value result is a promise that resolves into the same structure as the result structure returned from the parser (see above)

Examples

An example can be found in test.js
It contains the initialization of the parser, how to use it and how to work with the parsed project

To run the test/example:

yarn test path/to/knx/project/file.knxproj

Files

README.md

Latest commit

History

README.md

File metadata and controls

ETS-Project parser

Parse an ETS-Project

The structure of a parsed project

The parts of a parsed project

result.projectInformation

result.topology

result.topology.unassignedDevices[]

result.topology.areas[]

result.topology.areas[n].lines[]

result.topology.areas[n].lines[n1].devices[]

result.topology.areas[n].lines[n1].devices[n2].parameterReferences[]

result.topology.areas[n].lines[n1].devices[n2].communicationObjectReferences[]

result.buildings[]

result.groupAddresses[]

result.productLookupTable[]

result.manufacturerLookupTable[]

result.datapointLookupTable[]

result.mediumTypeLookupTable[]

result.deviceApplicationLookupTable

result.deviceMaskversionLookupTable

result.deviceMaskversionLookupTable.resources

Functions

result.get*ByKey(key, value)

result.getProjectInformation()

result.getAreas()

result.getAreaByKey(key, value)

result.getLines()

result.getLineByKey(key, value)

result.getUnassignedDevices()

result.getUnassignedDeviceByKey(key, value)

result.getDevices()

result.getDeviceByKey(key, value)

result.getBuildingParts()

result.getBuildingPartByKey(key, value)

result.getFunctions()

result.getFunctionByKey(key, value)

result.getGroupAddresses()

result.getGroupAddressByKey(key, value)

result.getProductFamilies()

result.getProductFamilyByKey(key, value)

result.getProducts()

result.getProductByKey(key, value)

result.getManufacturers()

result.getManufacturerByKey(key, value)

result.getDatapointTypes()

result.getDatapointTypeByKey(key, value)

result.getDatapointSubTypes()

result.getDatapointSubTypeByKey(key, value)

result.getMediumTypes()

result.getMediumTypeByKey(key, value)

result.getDeviceApplicationInformation()

result.getDeviceApplicationInformationByKey(key, value)

result.exportToJson(outputFilePath)