FIN 5.3.1 中文文档

外观

knxExt 扩展参考 ​

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793423129/FIN+5.3.1+knxExt 中文整理基于 FIN 5.3.1

导读： KNX 连接器扩展

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读） ​

  • classes
  • docs
  • Slot Details
    • doValUpdate
    • getProjFile
    • link
    • make
    • onClose
    • onCloseEvent
    • onHouseKeeping
    • onLearn
    • onOpen
    • onPing
    • onSyncCur
    • onUnwatch
    • onUpdated
    • onValUpdate
    • onWatch
    • onWrite
    • receive
    • addPropsToBranch
    • generateGridViewData
    • generateNodeProps
    • selectAction
    • body
    • commitAction
    • knxGetDataTypesFantom
    • toGrid
    • cur
    • onGet
    • knxDeleteProjectFiles
    • knxDeviceStatus
    • knxDevices
    • knxDpEditForm
    • knxEnableCustomEncoding
    • knxFindProjectFiles
    • knxGetDataTypes
    • knxGetQuantities
    • knxImportUnits
    • knxLearn
    • knxPing
    • knxProjectIsLocked
    • knxReadUnits
    • knxReplaceProjectFile
    • knxSyncCur
    • knxUpdateDataPoints
    • knxUpdateIndividualAddress
    • knxUploadProject
    • knxWatchdogDisable
    • knxWatchdogEnable
    • knxWatchdogStatus
    • knxWriteUnits
    • log
    • connProto
    • isCurSupported
    • isLearnSupported
    • isWriteSupported
    • pollingMode

概述（中译） ​

标题：KnxExt 作者：Ionut Enescu 创建日期：2020年8月20日 版权：版权所有 (c) 2020，J2 Innovations

概述 [概览]

[KnxExt]KnxExt::index pod 实现了对 KNX 协议的连接器支持。它遵循标准的连接器模型：

  • 连接器：用于配置 JKNXC 与 KNX 接入点（通常是 IP 接口）的连接
  • 功能：在您的 Axon 脚本中提供读取/写入/学习的访问

支持的协议 [支持]

目前 KnxExt 支持 KNX 协议的 KNXNet/IP 版本。读写仅通过隧道支持。

设置 [设置]

FIN 利用 JKNXC 基础设施来使用各种 KNX Java 驱动程序。所有 FIN JKNXC 驱动程序都实现了 JKNXC 接口，因此任何需要自定义驱动程序的人都可以简单地实现 JKNXC 接口。

用于设置：

  1. 确保您的 JKNXC 接口 (jknxc.jar) 和 JKNXC 驱动程序 (jknxc-xxx.jar) 已安装，并且可以通过系统类路径访问。最适合放置它的地方是在 "jre/lib/ext" 目录中。jknxc.jar 和 jknxc-xxx.jar 基于 Java：lib/java/ext/。在使用 jknxc-calimero 驱动程序的情况下，以下依赖项也应存在于相同位置：calimero-core-2.4.jar 和 slf4j-api-1.8.0-beta4.jar。待办事项：当 jknxc.jar 封装到 knx.pod 中时，需重新审视上述内容。 2. 确保 lib/fan/ 中同时存在 knxExt.pod 和 knx.pod。 3. 确保 KnxExt 已启用（FIN 高级应用 - 设置应用 - 扩展 - Knx）。

knxproj 文件 [ knxproj]

任何 KNX 配置的起点是使用 ETS 工具定义一个或多个安装的 KNX 拓扑，该工具可以从 KNX 协会网站（www.knx.org）下载。

导入 [ import]

在创建和配置 KNX 项目后，您将拥有一个 .knxproj 文件，可以将其导入到 FIN 中。要将 .knxproj 文件上传到 FIN 项目中，请进入 FIN 系统集成应用 - 数据库构建器 - 连接器 - Knx - 项目，点击上传按钮并选择您的 knxproj 文件。在同一视图中，您可以选择替换或删除已上传的 knxproj 文件。当您将 knxproj 文件上传到 FIN 项目时，该文件可用于该 FIN 项目下创建的所有 Knx 连接器。

API 正文（英文） ​

There are two things you need to provide in order to create a KNX connector: the KNX Project exported from the ETS tool and the connector URI. Once you have at least one knxproj file uploaded into the FIN project, you can go ahead and create a KNX connector. The connector URI has the following format: knx-[driver]😕/[IP]:[port]/, where:

  • driver – default is calimero, but you can have your own customized JKNXC driver
  • IP – the IP address of the KNX interface/gateway device you use to access the KNX network
  • port - default for KNX is 3671, but you can pick your own

The FIN Knx connector URI also has an enhanced version where a KNX Group Address can be appended it, i.e. knx-calimero://192.168.1.100:3671/2/0/3. Additionally, the appended group address can have wildcards, like 2/1/* or 1/*/5, which would allow for similar/identical functionalities to operate on a batch of group addresses instead of a single one.

You can test out your connector using the knxPing Axon function:

read(knxConn).knxPing

or by using the connector UI under the Equip Tree accessible from the DB Builder app.

Learning [#learning]

From the KnxConn view, you can discover the data points from the chosen *knxproj. Before learning a data point as a point in FIN, you have the ability to first edit its definition in the knxproj file by using the Edit Datapoint button in the point discovery interface. This can be used for datapoints that don’t originally come with a data point type assigned from the knxproj, to configure if they are readable and/or writable or if we need to change some of the point information before adding it to the equip. Once you've done that, you can select the points you want to add into the Equip Tree by clicking Add/Add all or drag and drop the point(s) under an equip. Note: when you edit a data point the changes you make are made on the imported knxproj file, therefore all other KnxConns using that *knxproj file will be impacted.

Besides the FIN Discover view, learning can calso be done using the KnxLearn Axon function as following:

read(knxConn).knxLearn

which returns a Grid of all discovered data points on that KnxConn.

Translation to FIN [#translation] ​

The Learning and Edit Datapoint views offer a great deal of flexibility in order to translate KNX data point types into Haystack types efficiently. For example, in the case of a DateTime DPT, KnxExt offers the possibility of selecting individual bits of the DPT, such month, minutes, day of the week.

Specifying the DPT [#dpt] ​

You can specify the data point type in the following formats:

  • 1.009 (close/open encoding)
  • DPST-1-9 (close/open encoding)
  • DPT-1 (generic boolean, no subtype)
  • DPST-4-1[0] (retrieves the increase/decrease encoding bit of the generic DPST-4-1 data point type, which is an 8-bit encoding)
  • 4 or 4-xxx (generic DPST-4-xxx type)
  • 4.001 (DPT subtype)
  • 4.009.0 (first part of the DPST-4-9 DPT)

Units [#units] ​

Units translation from KNX to Haystack is done via the units.props file found under /etc/sys/. In case your *.knxproj file defines a non-standard KNX unit, you can add it to the units.props file or change an already existing binding in that file. A FIN restart is required after altering this file.

Reading and writing [#rw]

Reading and writing on KNX can be performed on the same group address or on dedicated group addresses independently. For example, reading a batch of switches/binary outputs is done with the 1/1/* group addresses, while writing to these channels is performed with the 1/0/* group addresses, or they both reading and writing can be performed on the same group address.

Funcs [#funcs]

The following Axon funcs can be used to interface with the KnxExt:

  • knxPing : performs an async ping on a given connector.
  • knxSyncCur: asynchronously synchronize current values for given list of proxy points.
  • knxLearn : synchronous learn read on the given connector.
  • knxFindProjectFiles: searches for knxproj files in the following places: /var/proj/[proj_name]/io, /var/proj/[proj_name]/data/knx, inside the pods(uploads what it finds into FIN and tags it as knxProjFile), file records with knxProjFile tag
  • knxDeleteProjectFiles: deletes knxproj files from the FIN project
  • knxReplaceProjectFile: replaces knxproj files from the FIN project
  • knxUpdateDataPoints: writes changes performed on data points back to the knxproj used on a KnxConn
  • knxGetDataPoint: returns data for a specific data point
  • knxGetDataTypes: returns the data point types found in the knx_master.xml which is bundled in the *knxproj file assigned to a KnxConn

 

---

 

# KnxConn

`class KnxConn : Conn`

KnxConn

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [link](#link) |  |

 

**Methods**

|  |  |
| --- | --- |
| [doValUpdate](#doValUpdate) |  |
| [getProjFile](#getProjFile) |  |
| [onClose](#onClose) |  |
| [onCloseEvent](#onCloseEvent) |  |
| [onHouseKeeping](#onHouseKeeping) |  |
| [onLearn](#onLearn) |  |
| [onOpen](#onOpen) |  |
| [onPing](#onPing) |  |
| [onSyncCur](#onSyncCur) |  |
| [onUnwatch](#onUnwatch) |  |
| [onUpdated](#onUpdated) |  |
| [onValUpdate](#onValUpdate) |  |
| [onWatch](#onWatch) |  |
| [onWrite](#onWrite) |  |
| [receive](#receive) |  |

## Slot Details

---

 

### doValUpdate

`Void doValUpdate(Int addr, Buf buf)`

---

 

### getProjFile

`static KnxProjFile? getProjFile(Proj proj, Dict rec)`

---

 

### link

`KnxLink? link`

---

 

### make

`new make(ConnActor actor, Dict rec)`

---

 

### onClose

`virtual override Void onClose()`

---

 

### onCloseEvent

`static Void onCloseEvent(ConnActor actor, Err? err)`

---

 

### onHouseKeeping

`virtual override Void onHouseKeeping()`

---

 

### onLearn

`virtual override Grid onLearn(Obj? arg)`

---

 

### onOpen

`virtual override Void onOpen()`

---

 

### onPing

`virtual override Dict onPing()`

---

 

### onSyncCur

`virtual override Void onSyncCur(ConnPoint[] points)`

---

 

### onUnwatch

`virtual override Void onUnwatch(ConnPoint[] points)`

---

 

### onUpdated

`virtual override Void onUpdated(Dict oldRec, Dict newRec)`

---

 

### onValUpdate

`static Void onValUpdate(ConnActor actor, Int addr, Buf buf)`

---

 

### onWatch

`virtual override Void onWatch(ConnPoint[] points)`

---

 

### onWrite

`virtual override Void onWrite(ConnPoint point, Obj? val, Number level)`

---

 

### receive

`virtual override Obj? receive(ConnMsg msg)`

 

---

 

# KnxConnectorTree

`const class KnxConnectorTree : DbConnectorTree`

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Methods**

|  |  |
| --- | --- |
| [addPropsToBranch](#addPropsToBranch) |  |
| [generateGridViewData](#generateGridViewData) |  |
| [generateNodeProps](#generateNodeProps) |  |
| [selectAction](#selectAction) |  |

## Slot Details

---

 

### addPropsToBranch

`virtual override Dict[] addPropsToBranch(Grid branchGrid, Str? branchDis)`

---

 

### generateGridViewData

`virtual override Grid generateGridViewData(Obj? queryObj, Str branchTypeStr)`

---

 

### generateNodeProps

`virtual override Dict generateNodeProps(Dict connRec, Str? branchDis := null)`

---

 

### make

`new make(Str? treeDis := null)`

---

 

### selectAction

`virtual override Dict selectAction(Str queryStr, Dict opts)`

 

---

 

# KnxDpEditForm

`const class KnxDpEditForm : Obj`

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [body](#body) |  |
| [commitAction](#commitAction) |  |

 

**Methods**

|  |  |
| --- | --- |
| [knxGetDataTypesFantom](#knxGetDataTypesFantom) |  |
| [toGrid](#toGrid) |  |

## Slot Details

---

 

### body

`const Map[] body`

---

 

### commitAction

`const Str commitAction`

---

 

### knxGetDataTypesFantom

`static Grid knxGetDataTypesFantom(Ref connId, Number level, Str? id := null)`

---

 

### make

`new make(Ref connId, Uri[] dpAddrs)`

---

 

### toGrid

`Grid toGrid()`

 

---

 

# KnxExt

`@ExtMeta { name="knx"; depends=["conn","finstack"] }  
@FinExtMeta { licFeatureExclude="enterprise" }  
const class KnxExt : FinConnImplExt, Weblet`

 

**Methods**

|  |  |
| --- | --- |
| [cur](#cur) |  |
| [onGet](#onGet) |  |

## Slot Details

---

 

### cur

`static KnxExt cur()`

---

 

### onGet

`virtual override Void onGet()`

 

---

 

# KnxLib

`const class KnxLib : Obj`

Axon functions for knx

 

**Fields**

|  |  |
| --- | --- |
| [log](#log) |  |

 

**Methods**

|  |  |
| --- | --- |
| [knxDeleteProjectFiles](#knxDeleteProjectFiles) |  |
| [knxDeviceStatus](#knxDeviceStatus) | NOTE: This function is for TEST purposes only. |
| [knxDevices](#knxDevices) | Return a grid of all KNX devices found in the ETS project file for the given connector. |
| [knxDpEditForm](#knxDpEditForm) | Launches the data point edit form |
| [knxEnableCustomEncoding](#knxEnableCustomEncoding) | Method to configure encoding if KNX project import fail Parameters - `enable` : true - enable custom encoding, false - disable custom encoding |
| [knxFindProjectFiles](#knxFindProjectFiles) |  |
| [knxGetDataTypes](#knxGetDataTypes) | Retrieve the possible data types for the data point edit form's data type selectors |
| [knxGetQuantities](#knxGetQuantities) |  |
| [knxImportUnits](#knxImportUnits) |  |
| [knxLearn](#knxLearn) | Perform a synchronous learn read on the given connector. |
| [knxPing](#knxPing) | Perform an async ping on the given connector. |
| [knxProjectIsLocked](#knxProjectIsLocked) |  |
| [knxReadUnits](#knxReadUnits) |  |
| [knxReplaceProjectFile](#knxReplaceProjectFile) |  |
| [knxSyncCur](#knxSyncCur) | Asynchronously synchronize current values for given list of proxy points. |
| [knxUpdateDataPoints](#knxUpdateDataPoints) | Receives the updated values from the data point edit form |
| [knxUpdateIndividualAddress](#knxUpdateIndividualAddress) | Method to configure KNX individual address Parameters - `conn` : the KNX connection used to query the object properties - `addr`: KNX individual address |
| [knxUploadProject](#knxUploadProject) |  |
| [knxWatchdogDisable](#knxWatchdogDisable) | Disable the KNX watchdog for the given connector. |
| [knxWatchdogEnable](#knxWatchdogEnable) | Enable or configure the KNX watchdog for the given connector. |
| [knxWatchdogStatus](#knxWatchdogStatus) | Return a grid showing the cached watchdog connectivity status for all KNX devices. |
| [knxWriteUnits](#knxWriteUnits) | Write units |

## Slot Details

---

 

### knxDeleteProjectFiles

`@Axon  
static Void knxDeleteProjectFiles(Obj? files)`

---

 

### knxDeviceStatus

`@Axon { admin=true }  
static Grid knxDeviceStatus(Obj conn, Str? router := null, Obj? timeout := null)`

NOTE: This function is for TEST purposes only. Do NOT use in production. It generates live KNX bus traffic for every device and blocks the calling thread for the full duration. For production use, call `knxWatchdogStatus` which reads from the in-memory cache with zero bus traffic.

Check the connectivity status of KNX devices for the given connector. Routers are always pinged first. If a router is unreachable, all its bus devices (same area.line prefix) are marked "unreachable (router down)" without pinging them individually.

When a router individual address is provided, only that router and its bus devices are checked. When no router is specified, ALL routers and ALL bus devices are tested.

Parameters:

- conn: connector reference or id
- router: optional router individual address (e.g. "1.1.0") to filter by line
- timeout: optional ping timeout per device (default 10sec). Examples: 10sec, 30sec

Returns a grid with columns: individualAddr, dis, status, isRouter, checkedAt where status is "ok", "unreachable", or "unreachable (router down)".

Example:

knxDeviceStatus(@myKnxConn) // check all devices, default 10sec timeout knxDeviceStatus(@myKnxConn, "1.1.0") // check router 1.1.0 and its bus devices knxDeviceStatus(@myKnxConn, null, 30sec) // all devices, 30sec ping timeout knxDeviceStatus(@myKnxConn, "1.1.0", 15sec) // router filter with 15sec timeout


---

 

### knxDevices

`@Axon { admin=true }  
static Grid knxDevices(Obj conn)`

Return a grid of all KNX devices found in the ETS project file for the given connector. Each row contains the device's individual address, display name, description, serial number, product ref, and the resolved group addresses it is bound to. Router devices are included and marked with an `isRouter` column.

Example:

knxDevices(@myKnxConn)


---

 

### knxDpEditForm

`@Axon  
static Grid knxDpEditForm(Ref connId, Uri[] dpAddrs)`

Launches the data point edit form

---

 

### knxEnableCustomEncoding

`@Axon { admin=true }  
static Bool knxEnableCustomEncoding(Bool enable := true)`

Method to configure encoding if KNX project import fail Parameters

- `enable` : true - enable custom encoding, false - disable custom encoding

Example:

knxEnableCustomEncoding(true)

---

 

### knxFindProjectFiles

`@Axon  
static Grid knxFindProjectFiles()`

---

 

### knxGetDataTypes

`@Axon  
static Grid knxGetDataTypes(Ref connId, Number level, Str? id := null)`

Retrieve the possible data types for the data point edit form's data type selectors

---

 

### knxGetQuantities

`@Axon  
static Str[] knxGetQuantities()`

---

 

### knxImportUnits

`@Axon  
static Void knxImportUnits(Obj recId)`

---

 

### knxLearn

`@Axon { admin=true }  
static Grid knxLearn(Obj conn, Obj? arg)`

Perform a synchronous learn read on the given connector. Following columns are returned:

- `dis`: display name of point
- `kind`: point kind
- `modbusCur`: address to map to point
- `modbusWrite`: address if applicable to map to writable point
- `point`: point marker
- `unit`: unit if defined

---

 

### knxPing

`@Axon { admin=true }  
static Obj? knxPing(Obj conn)`

Perform an async ping on the given connector. If there is not an open connector, then this call first opens a new connection, verifies it can read a register, and then closes the connection. The following tags are updated:

- `curStatus`: ok if successful, down or fault is not
- `curErr`: error message on failure

---

 

### knxProjectIsLocked

`@Axon  
static Bool knxProjectIsLocked(Ref knxProjFileRef)`

---

 

### knxReadUnits

`@Axon  
static Grid knxReadUnits(Bool inclDef)`

---

 

### knxReplaceProjectFile

`@Axon  
static Obj? knxReplaceProjectFile(Dict original, Dict replacement, Bool hasPassword := false)`

---

 

### knxSyncCur

`@Axon { admin=true }  
static Obj? knxSyncCur(Obj points)`

Asynchronously synchronize current values for given list of proxy points. The point list may be any value supported by <toRecs>. The points must have the following tags configured:

- `modbusConnRef`
- `modbusCur`

This call updates the following point tags:

- `curVal`: current value of the point
- `curStatus`: status of the point (down/fault on failure)
- `curErr`: error message on failure

---

 

### knxUpdateDataPoints

`@Axon  
static Void knxUpdateDataPoints(Ref connId, Uri fileUri, Dict[] points)`

Receives the updated values from the data point edit form

---

 

### knxUpdateIndividualAddress

`@Axon { admin=true }  
static Bool knxUpdateIndividualAddress(Obj conn, Str addr)`

Method to configure KNX individual address Parameters

- `conn` : the KNX connection used to query the object properties
- `addr`: KNX individual address

Example:

knxUpdateIndividualAddress(@connRef, "1.0.0")

---

 

### knxUploadProject

`@Axon  
static Void knxUploadProject(Ref knxProjFileRef, Str secret := "")`

---

 

### knxWatchdogDisable

`@Axon { admin=true }  
static Obj? knxWatchdogDisable(Obj conn)`

Disable the KNX watchdog for the given connector. Removes the `knxWatchdogEnabled` and `knxWatchdogFreq` tags.

Parameters:

- conn: connector reference or id

Example:

knxWatchdogDisable(@myKnxConn)


---

 

### knxWatchdogEnable

`@Axon { admin=true }  
static Obj? knxWatchdogEnable(Obj conn, Obj? freq := null, Obj? batchSize := null, Obj? routerAware := true)`

Enable or configure the KNX watchdog for the given connector. Adds the `knxWatchdogEnabled` marker tag and optionally sets the poll frequency, batch size, and router-aware mode.

Parameters:

- conn: connector reference or id
- freq: optional poll frequency (default 5min, minimum 5min). Examples: 5min, 10min, 1hr
- batchSize: optional number of devices to ping per poll cycle (default 10, minimum 1)
- routerAware: optional boolean to enable router-aware mode (default true). When true, adds the `knxRouter` marker tag so the watchdog pings routers first and skips bus devices if their router is down.

Example:

knxWatchdogEnable(@myKnxConn) // default 5min freq, batch 10, router-aware knxWatchdogEnable(@myKnxConn, 30min) // 30min freq, batch 10, router-aware knxWatchdogEnable(@myKnxConn, 5min, 20) // 5min freq, batch 20, router-aware knxWatchdogEnable(@myKnxConn, 5min, null, false) // 5min freq, batch 10, no router awareness


---

 

### knxWatchdogStatus

`@Axon { admin=true }  
static Grid knxWatchdogStatus(Obj conn)`

Return a grid showing the cached watchdog connectivity status for all KNX devices. No bus traffic — reads from in-memory cache populated by the periodic watchdog poll. Columns: individualAddr, dis, status, isRouter, lastChecked.

The watchdog must be enabled on the connector by adding the `knxWatchdogEnabled` marker tag. Poll frequency is controlled by `knxWatchdogFreq` (default 5min).

Example:

knxWatchdogStatus(@myKnxConn)


---

 

### knxWriteUnits

`@Axon  
static Obj? knxWriteUnits(Obj? units)`

Write units

---

 

### log

`const static Log log := Log.get(KnxLib#.name())`

 

---

 

# KnxModel

`@Js  
const class KnxModel : ConnModel`

KnxModel

 

**Constructors**

|  |  |
| --- | --- |
| [make](#make) |  |

 

**Fields**

|  |  |
| --- | --- |
| [connProto](#connProto) |  |

 

**Methods**

|  |  |
| --- | --- |
| [isCurSupported](#isCurSupported) |  |
| [isLearnSupported](#isLearnSupported) |  |
| [isWriteSupported](#isWriteSupported) |  |
| [pollingMode](#pollingMode) |  |

## Slot Details

---

 

### connProto

`virtual const override Dict connProto`

---

 

### isCurSupported

`virtual override Bool isCurSupported()`

---

 

### isLearnSupported

`virtual override Bool isLearnSupported()`

---

 

### isWriteSupported

`virtual override Bool isWriteSupported()`

---

 

### make

`new make()`

---

 

### pollingMode

`virtual override PollingMode pollingMode()`