node-red-contrib-knx-ultimate/nodes/locales/en/knxUltimateRouterFilter.html

Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control, ETS group address importer, KNX AI for diagnosticsand KNX routing between interfaces. Easy to use and highly configurable.

<script type="text/markdown" data-help-name="knxUltimateRouterFilter">
Filters RAW telegram objects (typically produced by **KNX Multi Routing**) before they are forwarded to another gateway.

## Pattern syntax
- Group Address patterns support `*` per level:
  - `0/0/*` matches all group addresses in `0/0`
  - `0` means `0/*/*`
- Source (physical address) patterns support `*` per level:
  - `1.1.*` matches all devices on area `1`, line `1`
  - `1` means `1.*.*`
- Advanced: `re:<regex>` to use a regex directly.

## Mode (GA / Source)
- **Off**: no filtering
- **Allow only matching**: passes only items that match a pattern
- **Block matching**: drops items that match a pattern

## Outputs
1. **Passed** messages (to be forwarded)
2. **Dropped** messages (optional debug)

## Rewrite
You can optionally rewrite:
- destination Group Address (`knx.destination`)
- source physical address (`knx.source`)

When rewriting, the node also updates `knx.cemi.hex` to match the rewritten `knx.source`/`knx.destination` (when `knx.cemi.hex` is present).

Rewrite rules are evaluated top-to-bottom, first match wins.

Syntax examples:
- Wildcards: `0/0/* => 2/0/*` (the `*` is captured and reused)
- Regex: `re:^1/2/(\\d+)$ => 3/2/$1`

## Metadata
The node adds `msg.payload.knxRouterFilter`:
- dropped messages: `{ dropped: true, reason: 'event'|'ga'|'source', ... }`
- passed messages: `{ dropped: false, rewritten: <bool>, cemiSynced: <bool>, rewrite: { ... }, original: { ... } }`

## msg.setConfig
You can change the node configuration at runtime by sending a `msg.setConfig` object to the input.
Supported keys: `allowWrite`, `allowResponse`, `allowRead`, `gaMode`, `gaPatterns`, `srcMode`, `srcPatterns`, `rewriteGA`, `gaRewriteRules`, `rewriteSource`, `srcRewriteRules`.
The new configuration is retained until next `msg.setConfig` or until redeploy/restart. Configuration messages are not forwarded.

Meaning of the properties:
- `allowWrite`: allow `GroupValue_Write` telegrams.
- `allowResponse`: allow `GroupValue_Response` telegrams.
- `allowRead`: allow `GroupValue_Read` telegrams.
- `gaMode`: destination GA filter mode (`off` = no filter, `allow` = allow only matching, `block` = drop matching).
- `gaPatterns`: destination GA patterns used by `gaMode` (one per line, supports `*` and `re:<regex>`).
- `srcMode`: source (physical address) filter mode (`off`/`allow`/`block`).
- `srcPatterns`: source patterns used by `srcMode` (one per line, supports `*` and `re:<regex>`).
- `rewriteGA`: enable rewrite of `knx.destination` on passed telegrams.
- `gaRewriteRules`: rewrite rules for destination GA (`from => to`, first match wins; supports `*` and `re:<regex>`).
- `rewriteSource`: enable rewrite of `knx.source` on passed telegrams.
- `srcRewriteRules`: rewrite rules for source PA (`from => to`, first match wins; supports `*` and `re:<regex>`).

Example:
```js
msg.setConfig = {
  allowWrite: true,
  allowResponse: true,
  allowRead: true,
  gaMode: "allow",
  gaPatterns: "1/1/*\n1/2/3",
  srcMode: "off",
  srcPatterns: "",
  rewriteGA: true,
  gaRewriteRules: "5/5/1 => 1/1/1",
  rewriteSource: true,
  srcRewriteRules: "15.*.* => 1.1.254"
};
return msg;
```
</script>