knx.ts 1.0.1 → 1.0.4

package/LICENSE

@@ -1,21 +1,51 @@
-MIT License
-
-Copyright (c) 2025 Arnold Steven Beleño Zuletta
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,32 +1,88 @@
 # knx.ts
 
-A high-performance **KNXnet/IP** library written in **TypeScript**. This project focuses on protocol strictness and connection stability, specifically optimized to provide a reliable experience when used as a Gateway for ETS.
+Spanish version: see [readme-es.md](./readme-es.md).
 
-## 🌟 Current Capabilities
+A high-performance **KNXnet/IP** and **Hardware Interface** library such as **HID USB** and **TPUART**, written in **TypeScript**.
 
-- **Robust UDP Tunnelling**: Implements a strict *Stop-and-Wait* queue and sequence number management (KNX Spec Vol 3/8/4). This eliminates common "connection broken" issues in ETS during long sessions.
-- **KNXnet/IP Routing**: Supports standard multicast routing for seamless bus integration.
+This project focuses on protocol strictness, reading and sending any kind of **EMI** or **CEMI** message, broad DPT (Data Point Type) support, connection stability, and direct hardware integration, specifically optimized to provide a reliable experience when used as a Gateway for ETS or as a core for custom KNX controllers.
+
+## 🌟 Capabilities
+
+- **Robust UDP Tunneling**: Implements a strict *Stop-and-Wait* queue and sequence number management. This eliminates common "connection interrupted" issues in ETS or other applications during long sessions.
+- **KNXnet/IP Routing**: Supports multicast routing (only in the **KNXnet/IP** server).
+- **Discovery in the KNXnet/IP server**: Supports `SEARCH_REQUEST`, `SEARCH_REQUEST_EXTENDED`, `DESCRIPTION_REQUEST`, `CONNECT_REQUEST`, and `CONNECTIONSTATE_REQUEST` so applications such as ETS can discover it without manual configuration.
+- **Direct Hardware Interfaces**: Native support for **KNX USB interfaces** (via `node-hid`) and **TPUART** serial chips (via `serialport`).
+- **Learning Bridge (Router)**: Advanced multi-interface routing with Loop Prevention, Signature Tracking, and Individual Address (IA) learning, allowing you to bridge multiple physical interfaces and tunnels simultaneously.
 - **Intuitive Address-Based Events**: Listen to specific telegrams using group addresses as event names (e.g., `server.on("1/1/1", ...)`).
-- **Echo Cancellation**: Automatically filters out loopback messages to prevent telegram processing loops.
+- **Echo Cancellation**: Automatically filters loopback messages to prevent telegram processing loops.
 - **High Performance**: Optimized for Node.js environments with minimal overhead.
 
-## 🚧 Status: Experimental & Work-In-Progress
+## 🚧 Status: Experimental and In Development
 
-As per the `TODO.md`, several features are currently in an **experimental** state or under development:
+According to `TODO.md`, several features are currently **experimental** or under development:
 
-- **TCP Support**: Implementation is present but testing is currently in an experimental phase.
-- **TPUART Hardware**: Integration with TPUART chips via serial is implemented but awaits full hardware verification, this implementation is based from the knxd.
-- **Advanced Routing**: Complex routing between multiple Tunnels and TPUART via the `Router` class is under evaluation.
-- **Device Parameterization**: Support for *Programming Mode* (progMode) is planned to allow full device configuration via ETS.
+- **TCP Support**: The implementation is present, but testing is currently in an experimental phase.
+- **Device Parameterization**: Support for *Programming Mode* (`progMode`) is planned to allow full device configuration through ETS.
 - **Source Filtering**: Filtering based on source addresses and selective routing is on the roadmap.
+- **Use of NPDU, TPDU, and APDU layers**: EMI still needs to use them for correct deserialization.
 
-## 📦 Installation
+## 📦 Installation via git
 
 ```bash
 git clone https://github.com/Wesxt/KNX.ts.git
 cd KNX.ts
+npm install
+```
+
+## 📦 Installation via npm
+
+```bash
+npm install knx.ts
 ```
 
+## 🧩 External Dependencies
+
+This library depends on a few key modules, both external and native, to enable its full functionality:
+
+- **[Pino](https://getpino.io/)**: Used as the central logging engine. It is highly efficient, and the library exports a singleton logger so your application can share the same instance without overhead.
+- **[node-hid](https://github.com/node-hid/node-hid)**: Used by `KNXUSBConnection` to interact natively with KNX USB interfaces. Keep in mind that native modules may require build tools on some operating systems.
+- **[serialport](https://serialport.io/)**: Used by `TPUARTConnection` for direct UART communication. Like `node-hid`, this is a native module.
+
+## 📚 API Reference (What is exported)
+
+The library exposes a rich set of classes and utilities that allow both high-level usage and low-level protocol manipulation:
+
+### 1. Connections and Gateways
+
+These classes form the core of your interaction with the network. All of them inherit from a `KNXService` base and emit common events.
+
+- `KNXnetIPServer`: Creates a standard KNXnet/IP server (Gateway). Perfect for providing tunneling slots to ETS or other tunneling clients.
+- `KNXTunneling`: Connects as a client to an existing KNXnet/IP gateway.
+- `KNXUSBConnection`: Connects directly to local KNX USB interfaces (ABB, MDT, Weinzierl, Zennio, etc.).
+- `TPUARTConnection`: Connects directly to KNX through TPUART serial hardware.
+- `Router`: A powerful bridge that interconnects different hardware connections or tunneling clients (**KNXUSBConnection**). You can attach multiple `KNXService` instances to it (e.g., one USB connection and 5 tunnels), and it will automatically route telegrams between them, handling Individual Address learning and loop prevention.
+
+### 2. Data Conversion (DPTs)
+
+- `KnxDataDecode`: Static utility to decode raw `Buffer` payloads into standard JavaScript/TypeScript types (e.g., numbers, booleans) depending on the KNX Data Point Type (DPT).
+- `KnxDataEncoder`: Static utility to encode JavaScript/TypeScript values back into `Buffer` chunks ready to be sent onto the KNX bus.
+
+### 3. Core KNX Frames and Types
+
+For developers building advanced monitoring or injection tools, the library exports the entire internal frame structure:
+
+- `CEMI` / `EMI` classes for parsing and serializing Common EMI and legacy EMI frames.
+- `APDU`, `NPDU`, `TPDU` classes for manipulating the Network, Transport, and Application layers.
+- `ControlField` to parse and serialize the control field of CEMI or EMI messages.
+- `ExtendedControlField` to parse and serialize the `Extended Control Field` or `Control Field 2` of CEMI messages.
+- `AddressType` is an enum that helps identify the Address Type (AT) bit in `ExtendedControlField`, so you can know whether the destination address is group or individual.
+- `APCI` parses and serializes APCI values hosted between TPDU and APDU data. You must be careful because APCI uses 10 bits and writes into the 2 least significant bits of the byte shared with TPCI, while the following bits may belong to APCI or be data depending on the frame.
+- `APCIEnum` is an enum that helps write APCI values according to the specification. **Warning**: this enum assumes all commands inside it are 10-bit or 2-byte values within the `0x3FF` mask; those with 4-bit length are simply represented inside a `0x3C0` mask.
+- `TPCI` parses and serializes TPCI values in the TPDU layer.
+- `TPCIType` is an enum that helps write or identify TPCI values according to the specification.
+- `DPTs`: the library exports interfaces such as `DPT5001` or `DPT1`. These interfaces are used by `KnxDataDecode` to return JavaScript objects and by `KnxDataEncoder` as parameter types to convert them into `Buffer`s.
+- `ServiceMessage` is an interface implemented by all CEMI and EMI messages, and also by NPDU, TPDU, and APCI layers. This is useful because they all expose two helpful methods: `toBuffer` to serialize the instance into a buffer and `describe` to provide a human-readable view of the instance. **Note**: most exported classes in this library that do not implement this interface, such as `APCI`, still provide a `describe` method.
+
 ## 🛠️ Quick Start
 
 ### Create a KNXnet/IP Server (Gateway)
@@ -34,51 +90,72 @@ cd KNX.ts
 Perfect for creating a bridge between your IP network and the KNX bus.
 
 ```typescript
-import { KNXnetIPServer } from './src/index.ts';
+import { KNXnetIPServer, ServiceMessage, KnxDataDecode } from 'knx.ts';
 
 const server = new KNXnetIPServer({
   localIp: '192.168.1.50',
-  individualAddress: '1.1.0', 
-  friendlyName: 'TypeScript KNX Gateway',
-  clientAddrs: '1.1.10:5' // Provide 5 tunneling slots starting from 1.1.10
+  individualAddress: '1.1.0', // Be careful not to create conflicts
+  friendlyName: 'TypeScript KNX Gateway', // This name is shown in ETS
+  clientAddrs: '1.1.10:5' // Provides 5 tunneling slots starting from 1.1.10
 });
 
 server.connect().then(() => {
-  console.log('KNXnet/IP Server is up and running');
+  console.log('The KNXnet/IP server is running');
 });
 
-// Specific listening for a Group Address
-server.on('1/1/1', (cemi) => {
-  console.log('New data on 1/1/1:', cemi.TPDU.apdu.data);
+// Specific listener for a Group Address
+server.on('1/1/1', (cemi: ServiceMessage) => {
+  console.log('New data on 1/1/1:', cemi.TPDU.apdu.data); // Raw APDU data
+  console.log('Decoded data:', KnxDataDecode.decodeThis("1.001", cemi.TPDU.apdu.data)); // Converted JavaScript value
+});
+```
+
+### Direct USB Connection
+
+```typescript
+import { KNXUSBConnection } from 'knx.ts';
+
+const usb = new KNXUSBConnection({
+  // Omitting path/vendorId will automatically discover the first known KNX USB interface
+});
+
+usb.connect().then(() => {
+  console.log('Connected directly to the KNX USB interface');
+});
+
+usb.on('indication', (cemi) => {
+  console.log('USB telegram source:', cemi.sourceAddress);
 });
 ```
 
 ### Tunneling Client
 
 ```typescript
-import { KNXTunneling } from './src/index.ts';
+import { KNXTunneling } from 'knx.ts';
 
 const tunnel = new KNXTunneling({
-  ip: '192.168.1.100', 
+  ip: '192.168.1.100',
   port: 3671,
   localIp: '192.168.1.50'
 });
 
 tunnel.connect().then(() => {
-  console.log('Connected to KNX Bus');
+  console.log('Connected to the KNX bus');
 });
 ```
 
 ## 📝 Logging
 
-The library uses a global singleton logger based on [Pino](https://github.com/pinojs/pino). You can configure it at the very beginning of your application using `setupLogger`.
+The library uses a single global logger based on [Pino](https://getpino.io/). You can configure it at the beginning of your application using `setupLogger`.
+
+This is important because you do not need to instantiate Pino yourself; the internal `knxLogger` manages its state to avoid the performance overhead of multiple instances.
 
 ```typescript
-import { setupLogger, knxLogger } from './src/index.ts';
+import { setupLogger, knxLogger } from 'knx.ts';
 
 // Configure the global logger
 setupLogger({
-  level: 'debug', // e.g., 'info', 'warn', 'error', 'debug'
+  level: 'debug', // e.g. 'info', 'warn', 'error', 'debug'
   logToFile: true,
   logDir: './logs',
 });
@@ -87,103 +164,239 @@ setupLogger({
 knxLogger.info("Application started");
 ```
 
-All internal components (`KNXnetIPServer`, `KNXTunneling`, `Router`, etc.) automatically use this shared logger to avoid spawning multiple Pino instances.
+All internal components (`KNXnetIPServer`, `KNXTunneling`, `Router`, etc.) automatically use this shared logger.
 
-## 📡 Events & Callbacks
+## 📡 Events and Callbacks
 
-The library is event-driven. You can listen for system events or specific KNX Group Addresses.
+The library is event-driven. Depending on the class you use, different events are emitted to provide detailed control and monitoring.
 
 ### Common Events
 
-Both `KNXnetIPServer` and `KNXTunneling` emit the following events:
+All connection classes (`KNXnetIPServer`, `KNXTunneling`, `KNXUSBConnection`, `TPUARTConnection`) inherit from `KNXService` and emit the following standard events:
 
 | Event | Description | Callback Arguments |
-|-------|-------------|--------------------|
-| `connected` | Connection established and ready. | `void` (Server) / `{ channelId }` (Tunnel) |
-| `disconnected` | Connection lost or closed. | `void` |
-| `error` | An error occurred during operation. | `Error` |
-| `indication` | Any incoming KNX telegram (L_Data.ind). | `cemi: L_Data_ind` |
+|--------|-------------|-------------------------|
+| `connected` | Connection established and hardware/socket ready. | `void` (Server/USB/TPUART) / `{ channelId }` (Tunnel) |
+| `disconnected` | Connection lost or explicitly closed. | `void` |
+| `error` | A fatal error occurred during operation. | `err: Error` |
+| `indication` | Any incoming standard KNX telegram (cEMI / L_Data.ind). | `cemi: ServiceMessage` |
+| `raw_indication`| The raw `Buffer` before parsing (EMI/cEMI/payload). | `data: Buffer` |
 
-### Address-Based Events (Server Only)
+### Class-Specific Events
 
-You can listen to specific Group Addresses directly:
+Depending on the connection type, some classes emit additional specific events:
 
-```typescript
-server.on("1/1/1", (cemi) => {
-  // Triggered only for telegrams to 1/1/1
-});
-```
+#### **KNXnetIPServer**
+
+- `queue_overflow`: Fired when the internal tunneling queue for a connected client overflows.
+- `<GroupAddress>` (e.g., `"1/1/1"`): Listen directly to specific group addresses (e.g., `server.on("1/1/1", (cemi) => {...})`).
+
+#### **TPUARTConnection**
+
+- `busmonitor`: Emitted in Busmonitor mode with raw cEMI frames.
+- `bus_ack`: Emitted when the bus confirms a transmission (Ack, Nack, Busy).
+- `warning`: Emitted for non-fatal hardware warnings (e.g., slave collision detected, transmission error).
+
+#### **KNXUSBConnection**
+
+- `indication_emi`: Emitted when an older EMI1/EMI2-formatted message is received from legacy USB interfaces.
+
+#### **KNXTunneling**
+
+- `feature_info`: Emitted when querying the features supported by a KNXnet/IP server.
+- `raw_message`: Emitted with the raw IP payload (including full KNXnet/IP headers, not only cEMI).
+
+#### **Router (Learning Bridge)**
+
+Because `Router` links multiple interfaces, it emits link-specific routing events instead of standard indications:
+
+- `indication_link`: Emitted when a packet is routed through the bridge. Argument: `{ src: string, msg: ServiceMessage }`, where `src` is the class name of the source connection.
+- `error`: Emitted when an underlying link fails. Argument: `{ link: KNXService, error: Error }`.
 
-### Understanding the `cemi` Object
+### Understanding the Telegram Object
 
-The `cemi` object (specifically `L_Data_ind`) contains all the information about the KNX telegram. Here are the most relevant properties:
+The `cemi` or `emi` object (implementing `ServiceMessage`) contains all the information about the KNX telegram. Here are the most relevant properties:
 
 | Property | Type | Description |
-|----------|------|-------------|
+|-----------|------|-------------|
 | `sourceAddress` | `string` | Physical address of the sender (e.g., `"1.1.5"`). |
-| `destinationAddress` | `string` | Group address (e.g., `"1/1/1"`) or Physical address. |
+| `destinationAddress` | `string` | Group address (e.g., `"1/1/1"`) or physical address. |
 | `TPDU.apdu.data` | `Buffer` | The raw payload data. |
 | `TPDU.apdu.apci.command` | `string` | Command type (`A_GroupValue_Write`, `A_GroupValue_Read`, etc.). |
 
 #### Handling Data Payloads
 
-KNX handles data in two ways depending on the size:
+KNX handles data in two ways depending on size:
 
-- **Short Data (<= 6 bits)**: For DPT1 (Switch), DPT3 (Control), etc. The `cemi.TPDU.apdu.data[0]` contains the value.
-- **Extended Data (> 6 bits)**: For DPT5 (Scaling), DPT9 (Float), etc. The `cemi.TPDU.apdu.data` Buffer contains the full payload (e.g., 2 bytes for DPT9).
+- **Short Data (<= 6 bits)**: For DPT1 (Switch), DPT3 (Control), etc. `cemi.TPDU.apdu.data[0]` contains the value.
+- **Extended Data (> 6 bits)**: For DPT5 (Scaling), DPT9 (Float), etc. The `cemi.TPDU.apdu.data` buffer contains the full payload (e.g., 2 bytes for DPT9).
 
-## 🔢 Data Encoding & Decoding
+## 🔢 Data Encoding and Decoding
 
-The library provides static utilities to handle KNX Data Point Types (DPT) conversion between raw Buffers and high-level TypeScript objects.
+The library provides static utilities to handle conversion of KNX Data Point Types (DPT) between raw buffers and high-level TypeScript objects.
 
 ### Decoding Incoming Data
 
-Use `KnxDataDecode` to transform raw CEMI data into readable values:
+Use `KnxDataDecode` to transform raw cEMI data into readable values. There are several methods with the `asDpt` prefix for specific cases; `decodeThis` is convenient if you do not want to deal with those directly:
 
 ```typescript
-import { KnxDataDecode } from './src/core/data/KNXDataDecode';
+import { KnxDataDecode } from 'knx.ts';
 
 server.on('1/1/1', (cemi) => {
   // Decode as DPT 1 (Boolean)
   const value = KnxDataDecode.decodeThis(1, cemi.TPDU.apdu.data);
   console.log('Decoded value:', value); // true or false
 
-  // Decode as DPT 9 (2-byte Float, e.g., Temperature)
+  // Decode only as DPT 1 (Boolean)
+  const value1 = KnxDataDecode.asDpt1(cemi.TPDU.apdu.data);
+
+  // Decode as DPT 9 (2-byte float, e.g. Temperature)
   const temp = KnxDataDecode.decodeThis(9, cemi.TPDU.apdu.data);
   console.log('Temperature:', temp, '°C');
+
+  // The first parameter also accepts strings with the standard DPT numbering
+  const temp1 = KnxDataDecode.decodeThis("9", cemi.TPDU.apdu.data)
+  const percentage = KnxDataDecode.decodeThis("5.001", cemi.TPDU.apdu.data)
 });
 ```
 
 ### Encoding Data for Sending
 
-Use `KnxDataEncoder` with the `encodeThis` method to prepare buffers for KNX telegrams; the second parameter is always an object (Problem: all DPTs other than DPT1 belonging to a property are different keys instead of just "value" values; this will be fixed in the future):
+Use `KnxDataEncoder` with the `encodeThis` method to prepare buffers for KNX telegrams; the second parameter is always an object. There are several `encodeDpt`-prefixed methods for specific cases, but `encodeThis` is convenient if you do not want to deal with those directly:
 
 ```typescript
-import { KnxDataEncoder } from './src/core/data/KNXDataEncode';
+import { KnxDataEncoder } from 'knx.ts';
 
 // Encode a Boolean (DPT 1)
 const buf1 = KnxDataEncoder.encodeThis(1, { value: true });
 
 // Encode a Percentage (DPT 5.001)
-const buf5 = KnxDataEncoder.encodeThis(5.001, { valueDpt5001: 50 });
+const bufOnly5 = KnxDataEncoder.encodeDpt5({ valueDpt5001: 50 });
+const buf5 = KnxDataEncoder.encodeThis(5001, { valueDpt5001: 50 });
+const buf5001 = KnxDataEncoder.encodeThis("5.001", { valueDpt5001: 50 });
 
 // Encode a Temperature (DPT 9.001)
 const buf9 = KnxDataEncoder.encodeThis(9, { valueDpt9: 22.5 });
 ```
 
-### Type Safety & IntelliSense
+### Type Safety and IntelliSense
 
 Both `KnxDataDecode.decodeThis()` and `KnxDataEncoder.encodeThis()` are strictly typed. This means:
 
-- **IntelliSense Support**: Your IDE will automatically suggest the supported DPTs as you type the first parameter.
+- **IntelliSense Support**: Your IDE will automatically suggest supported DPTs as you type the first parameter.
 - **Automatic Data Validation**: The second parameter (the data object) automatically adjusts its required properties based on the DPT selected in the first parameter.
-- **Supported DPTs**: You can programmatically check the list of supported DPTs by accessing the static `dptEnum` property:
+- **Supported DPTs**: You can programmatically inspect the list of supported DPTs (they return an array of numbers):
 
   ```typescript
   console.log(KnxDataDecode.dptEnum);
   console.log(KnxDataEncoder.dptEnum);
   ```
 
+## 🧪 Manual Message Construction and Sending (Experimental)
+
+The library exports low-level classes for building or reading **cEMI** and **EMI** messages in a granular way. This is useful for diagnostics, custom telegram injection, or implementing services not covered by the high-level API.
+
+### Hierarchy of a KNX Message
+
+In the actual API of this project, you typically build the **APDU** and **TPDU** layers first, and then create the final **cEMI** or **EMI** service. For a standard `L_Data.req` telegram, the final class is `CEMI.DataLinkLayerCEMI["L_Data.req"]`.
+
+#### 1. APDU (Application Protocol Data Unit)
+
+Defines the command (**APCI**) and the message data.
+
+```typescript
+import { APDU, APCI, APCIEnum } from 'knx.ts';
+
+const apci = new APCI(APCIEnum.A_GroupValue_Write_Protocol_Data_Unit);
+const apdu = new APDU(undefined, apci, Buffer.from([0x01]), true);
+```
+
+#### 2. TPDU (Transport Protocol Data Unit)
+
+Wraps the APDU and defines the transport type.
+
+```typescript
+import { TPDU, TPCI, TPCIType } from 'knx.ts';
+
+const tpdu = new TPDU(
+  new TPCI(TPCIType.T_DATA_GROUP_PDU),
+  apdu,
+  apdu.data,
+);
+```
+
+#### 3. cEMI `L_Data.req`
+
+In this library you do not build a generic `new CEMI()` for this case. You must instantiate the concrete cEMI service and pass its control fields, addresses, and `TPDU`.
+
+```typescript
+import {
+  AddressType,
+  CEMI,
+  ControlField,
+  ExtendedControlField,
+  Priority,
+} from 'knx.ts';
+
+const controlField1 = new ControlField();
+controlField1.frameType = true;
+controlField1.priority = Priority.LOW;
+
+const controlField2 = new ExtendedControlField();
+controlField2.addressType = AddressType.GROUP;
+controlField2.hopCount = 6;
+
+const cemi = new CEMI.DataLinkLayerCEMI["L_Data.req"](
+  null,
+  controlField1,
+  controlField2,
+  "1.1.1",
+  "1/1/1",
+  tpdu,
+);
+```
+
+#### 4. Additional Information (optional)
+
+`AdditionalInformationField` is not filled by assigning `type` and `data` manually. You must create instances of the concrete types defined in `KNXAddInfoTypes` and add them to the field.
+
+```typescript
+import {
+  AdditionalInformationField,
+  ManufacturerSpecificData,
+} from 'knx.ts';
+
+const addInfo = new AdditionalInformationField();
+const manufacturerInfo = new ManufacturerSpecificData();
+manufacturerInfo.data = Buffer.from([0x00, 0x01]);
+addInfo.add(manufacturerInfo);
+
+cemi.additionalInfo = addInfo;
+```
+
+#### 5. EMI (External Message Interface)
+
+`EMI` is also not used as a generic instance with `new EMI()`. The class acts as a service container and parser (`EMI.fromBuffer(...)`). In connections such as `KNXUSBConnection`, the library automatically converts a cEMI `ServiceMessage` to EMI when needed.
+
+### Final Assembly and Sending Example
+
+Once the structure is built, you can send it directly as a `ServiceMessage`, or serialize it with `toBuffer()` if you really need the raw buffer.
+
+```typescript
+import { KNXTunneling } from 'knx.ts';
+
+const tunnel = new KNXTunneling({
+  ip: '192.168.1.10',
+  port: 3671,
+});
+
+await tunnel.connect();
+await tunnel.send(cemi);
+
+// If you need the serialized buffer:
+await tunnel.send(cemi.toBuffer());
+```
+
 ## 🛠️ Development
 
 To build the project:
@@ -208,4 +421,4 @@ npm run test:connection
 
 ## ⚖️ License
 
-This project is licensed under the MIT License.
+This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.