knx_parser 1.9.0

A Dart library to parse KNX project files (.knxproj) from ETS5 and ETS6, including encrypted projects. Extracts data to JSON format.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.9.0 - 2026-03-17

Added

• Typed flat model: New KnxFlatProject with typed classes (KnxFloor, KnxRoom, KnxDevice, KnxGroupAddress, KnxGroupRange, KnxSecureKeys, KnxGaSecureKey, KnxDeviceToolKey).
• toFlat() method on KnxProject returns typed KnxFlatProject instead of raw Map.
• parseToFlat() convenience method on KnxProjectParser.
• GA-device mapping: KnxGroupAddress.deviceIds shows which devices reference each group address via comObject links.
• DPT format conversion: datapointType in flat output now uses x.yyy format (e.g., 9.001) instead of raw DPST-x-y.
• Exported DeviceInstance and KnxFlatProject models from library.

Changed

• toFlatJson() now delegates to toFlat().toJson().

1.8.0 - 2026-03-16

Added

• Flat JSON output format: New toFlatJson() method on KnxProject produces an organized, flat JSON with separate lists for floors, rooms, devices, groupAddresses, datapointTypes, and secureKeys.
• Device-to-room mapping: Location model now includes deviceInstanceIds field, parsed from DeviceInstanceRef elements inside Space XML nodes.
• Security detection: hasSecure boolean in flat JSON output, auto-detected from GA keys and device security tool keys.
• parseToFlatJson() and parseToFlatJsonFile() convenience methods on KnxProjectParser.

Changed

• Location.fromXml() now parses DeviceInstanceRef children.
• Location.toJson() includes deviceInstanceIds when non-empty.

1.7.1 - 2026-02-09

Changed

• Downgraded dependencies for Flutter 3.7.12 (Dart 2.19) compatibility:
  • archive: ^3.3.9
  • xml: ^6.3.0
  • pointycastle: ^3.7.3
  • lints: ^2.1.1

1.7.0 - 2026-02-09

Added

• Device name parsing: Device names are now extracted from Product catalog (M-*/Hardware.xml) and merged into DeviceInstance objects.
• copyWithName() method to DeviceInstance.
• copyWithProductCatalog() method to Segment, Line, Area, Topology, and Installation for immutable updates.

Fixed

• Device name was previously always null because DeviceInstance XML elements don't contain Name attribute. Now correctly extracted from manufacturer's Hardware.xml.

1.6.0 - 2026-02-03

Added

• ETS version detection: Added etsVersion ("ETS5" or "ETS6") and schemaVersion fields to ProjectInfo and JSON output.
• ETS6 Segment device support: Fixed parsing of DeviceInstance elements nested within Segment tags (ETS6 structure).

Changed

• Segment class now includes a devices property to support ETS6 project structure.
• Line.fromXml now combines devices from both direct children (ETS5) and Segment children (ETS6).

1.5.0 - 2026-02-02

Changed

• Improved handling of ETS5 outer .knxproj archives that are not password-protected while still supporting ETS6 outer-encrypted projects.
• Refined error messages and comments to be fully in English for cleaner public API diagnostics.

1.4.0 - 2026-02-02

Added

• Web support: Library can be compiled for web (dart compile js). Use parseBytes(List<int> bytes, ...) in the browser; parse(String filePath) and file-based APIs remain VM-only via conditional import.
• io_stub.dart for web builds (stub for dart:io when dart.library.html is defined).

Changed

• Parser uses conditional import dart:io / io_stub so the same code runs on VM and web.
• File.exists / Directory.exists usage aligned with dart:io API (getter, no parentheses).

1.3.0 - 2026-01-27

Added

• ETS6 encryption support: Implements PBKDF2-HMAC-SHA256 password derivation for ETS6 encrypted projects.
• Auto-detection of ETS version based on schema version (ETS6 = schema >= 21).
• Support for both ETS5 (raw password) and ETS6 (derived password) encrypted projects.

Dependencies

• Added pointycastle: ^3.9.1 for PBKDF2 key derivation.
• Added crypto: ^3.0.3 for cryptographic operations.

1.2.0 - 2026-01-26

Added

• Support for parsing secure KNX projects (AES encrypted P-*.zip files) with password.
• Parsing of DeviceInstance elements in Topology.
• Parsing of Security keys (ToolKey) for devices.
• Parsing of Key for Group Addresses.
• Updated JSON export to include new device and security data.

1.0.0 - 2026-01-26

• Initial release
• Parse .knxproj files (ZIP-based XML format from ETS6)
• Extract project information (name, GUID, dates, style)
• Extract topology (Areas, Lines, Segments)
• Extract group addresses with formatted address support (e.g., 0/0/1)
• Extract group ranges with hierarchical structure
• Extract locations (Buildings, Spaces)
• Parse datapoint types (DPT) from knx_master.xml
• Export to structured JSON format
• Comprehensive unit tests
• Example usage script

Dependencies

• archive: ^3.6.1 - ZIP file handling
• xml: ^6.5.0 - XML parsing