FIN 5.3.1 中文文档

外观

finBacnetExt 扩展参考 ​

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

导读： Fin BACnet 扩展

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

目录（导读） ​

  • classes
  • docs
  • Overview
  • Slot Details
    • _conn
    • _jobs
    • _objCount
    • _objs
    • client
    • conn
    • each
    • job
    • jobs
    • log
    • make
    • makeObjectListStatus
    • makePointsTypeListStatus
    • objs
    • readObjectList
    • readPoint
    • readPointsTypeList
    • receive
    • cachedDiscovery
    • cur
    • getLearner
    • purgeLearner
    • bacnetAsyncLearn
    • bacnetGetAlarms
    • bacnetGetEvents
    • bacnetReadFile
    • bacnetReinitializeDevice
    • bacnetWriteFile
    • finAutoSelectTemplates
    • finBacnetActiveAlarms
    • finBacnetCachedTemplateDiscovery
    • finBacnetClearCache
    • finBacnetClearCachedTemplateDiscovery
    • finBacnetConnStats
    • finBacnetCreatEquip
    • finBacnetDiscoveryTags
    • finBacnetFilterDevices
    • finBacnetTemplateDiscovery
    • finBacnetTemplateDiscoveryAdd
    • finBacnetTemplateDiscoveryPreview
    • finBacnetTemplateRead
    • finBacnetTemplates
    • finTemplateGenerateFunc
    • finTemplateOn
    • addDevice
    • getDevices
    • updateDiscoveryInfo
    • name
    • progress
    • grid
    • ts
    • ctx
    • dev
    • mustReadObjects
    • separateObjects
    • typePropTag
    • typeProps
    • rows

API 正文（英文） ​

Overview ​

This Fin BACnet extension extends the core BACnet extension with some productivity tools found in FIN Framework.

BacnetLearner ​

const class BacnetLearner : Actor

Constructors

make

Fields

_conn
_jobs
_objCount
_objs

Methods

client
conn
each
job
jobs
log
makeObjectListStatus
makePointsTypeListStatus
objs
readObjectList
readPoint
readPointsTypeList
receive

Slot Details ​

_conn ​

const Unsafe _conn

_jobs ​

const Unsafe _jobs

_objCount ​

const AtomicInt _objCount

_objs ​

const Unsafe _objs

client ​

ClientConnection? client()

conn ​

BacnetConn conn()

each ​

Void each(Range r, Func fx)

job ​

JobStatus? job(Str name)

jobs ​

Str:JobStatus jobs()

log ​

Log log()

make ​

new make(BacnetConn conn)

makeObjectListStatus ​

Grid makeObjectListStatus(Obj[] row, Int? progress := null)

makePointsTypeListStatus ​

Grid makePointsTypeListStatus(Str:Str[] points, Int? progress := null)

objs ​

Uri:Str:Str[] objs()

readObjectList ​

Grid readObjectList()

readPoint ​

Grid readPoint(Str curAddress)

readPointsTypeList ​

Grid readPointsTypeList(Uri path)

receive ​

virtual override Obj? receive(Obj? msg)

DrillDownMsg ​

const class DrillDownMsg : Obj

Slot Details ​

FinBacnetExt ​

@ExtMeta { name="finBacnet"; depends=["bacnet","finstack"] } @FinExtMeta { licFeature="finstack"; licFeatureExclude="enterprise"; pngIcon=`fan://bacnetExt/res/img/icon24.png` } const class FinBacnetExt : FinExt

Methods

cachedDiscovery
cur
getLearner
purgeLearner

Slot Details ​

cachedDiscovery ​

TemplateDiscoveryEntry cachedDiscovery()

cur ​

static FinBacnetExt? cur(Bool checked := true)

getLearner ​

BacnetLearner getLearner(BacnetConn conn)

purgeLearner ​

Void purgeLearner(BacnetConn conn)

FinBacnetLib ​

class FinBacnetLib : Obj

Fields

log

Methods

bacnetAsyncLearnDoes a deep learn operation on the device the conn parameter points to, but in a asynchronous way.
bacnetGetAlarms==== [DEPRECATED] - use function 'bacnetGetHandledAlarms(Obj conn)' ====
bacnetGetEventsReturns the unhandled events of Bacnet connector
bacnetReadFileReads the content of a BACnet File object.
bacnetReinitializeDeviceSend a BACnet reinitializeDevice request to the device the conn parameter points to.
bacnetWriteFileWrites the content of a IOHandle to a BACnet File object.
finAutoSelectTemplatesThis is the logic that finTemplateOn uses to match templates with a connector.
finBacnetActiveAlarmsReturn the active alarm(s) record(s).
finBacnetCachedTemplateDiscoveryPerforms the same operation as finBacnetTemplateDiscovery and caches the resulting discovery Grid for the next 15 minutes For clearing this cache call finBacnetClearCachedTemplateDiscovery
finBacnetClearCache
finBacnetClearCachedTemplateDiscoveryClear any previously cached template discovery
finBacnetConnStatsReturns a Grid with various details about the BACnet connection and the device this connection is made to.
finBacnetCreatEquipCreates equipment, sub-equipment and points under each sub-equipment.
finBacnetDiscoveryTagsGives the predefined set of tags, that will be used for a BACnet discovery.
finBacnetFilterDevicesReceives a list (as a grid) of bacnet devices and filters the ones that are not already added in the DB.
finBacnetTemplateDiscoveryPerforms a BACnet discovery and reads the properties specified in the set of predefined tags.
finBacnetTemplateDiscoveryAddAdds the device records found in a discovery session and reads additional properties specified in the predefined template tags.
finBacnetTemplateDiscoveryPreviewThis previews the connectors that will be made by the finBacnetTemplateDiscoveryAdd function.
finBacnetTemplateReadRead for the given devices, all the properties defined in the template pods.
finBacnetTemplatesThis is a replacement for the old SysLib.templates() function who's functionality has changed drastically.
finTemplateGenerateFuncThis is the logic that finTemplateOn uses to create the function to run on a template.
finTemplateOnThis will search for a templateOn tag in the current project and if the Filter expression matches records from the grid, then it will execute the funcTemplate tag expression on the matching record of the discovered grid.

Slot Details ​

bacnetAsyncLearn ​

@Axon static Grid bacnetAsyncLearn(Obj conn, Obj? path := null)

Does a deep learn operation on the device the conn parameter points to, but in a asynchronous way. If the learn process is not complete, the returned <Grid> will contain a Number tag called progress in its meta data.

Clients of this function should display a wait progress based on the metadata progress tag.

Example:

// learn all objects, display the object types
bacnetAsyncLearn(@conn)
// learn all objects, display only analog input objects
bacnetAsyncLearn(@conn, `ANALOG_INPUT`)

bacnetGetAlarms ​

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

====  [DEPRECATED] - use function 'bacnetGetHandledAlarms(Obj conn)'  ====

bacnetGetEvents ​

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

Returns the unhandled events of Bacnet connector

Accepts as parameters:

  • conn: the BACnet connection used to query the object properties

Examples:

bacnetGetAlarms(@connRef)

bacnetReadFile ​

@Axon { admin=true } static Dict bacnetReadFile(Obj conn, Obj id, Obj handle, Number offset := Number.<ctor>(0), Number count := Number.<ctor>(Int.maxVal))

Reads the content of a BACnet File object.

Parameters:

  • conn:Obj, a BACnet connection id or record
  • id:Str, a BAcnet File object identifier
  • handle:Obj, and IOHandle to be used to write what is read from the BACnet file.
  • offset:Num, the offset position or the record from where to start to read from the file
  • count:Num, how many bytes/records to be read, defaults to max

Returns:

a Dict with these columns

  • size:Num, the total size read (bytes/records)
  • eof:Bool, marks the end of file

Example:

bacnetReadFile(@connRef, "10:1", `io/bacnetFile`)

bacnetReinitializeDevice ​

@Axon { admin=true } static Grid bacnetReinitializeDevice(Obj conn, Obj reinitVal, Str? password := "")

Send a BACnet reinitializeDevice request to the device the conn parameter points to.

Parameters:

  • state:Obj, the state the device will be in, valid values: "cold_start", "warm_start", "start_backup", "end_backup", "start_restore", "end_restore", "abort_restore" or numeric values from 0 to 6 corresponding to the enumeration above
  • password:Str, optional password parameter

Example:

bacnetReinitializeDevice(@conn, "start_restore")

Returns:

`Grid` with one column, success:Marker

bacnetWriteFile ​

@Axon { admin=true } static Dict bacnetWriteFile(Obj conn, Obj id, Obj handle, Number offset := Number.<ctor>(0), Number count := Number.<ctor>(Int.maxVal))

Writes the content of a IOHandle to a BACnet File object.

Parameters:

  • conn:Obj, a BACnet connection id or record
  • id:Str, a BAcnet File object identifier
  • handle:Obj, and IOHandle to be used to read the data to be written to the BACnet file.
  • offset:Num, the offset position or the record from where to start to write the BACnet file
  • count:Num, how many records to be written, defaults to max

Returns:

a Dict with these columns

  • size:Num, the total size written (bytes/records)
  • startPosition:Num, the start position/record of the new file

Example:

bacnetWriteFile(@connRef, "10:1", `io/bacnetFile`)

finAutoSelectTemplates ​

@Axon { admin=true } static List finAutoSelectTemplates(Obj connIds)

This is the logic that finTemplateOn uses to match templates with a connector.

It returns a list of dicts looking like this:

This will search for a templateOn tag in the current project and if the Filter expression matches records from the grid, then it will return the funcTemplate tag expression on the matching record of the discovered grid.

finBacnetActiveAlarms ​

@Axon static Grid finBacnetActiveAlarms(Dict[] alarmRecords)

Return the active alarm(s) record(s). An active alarm is determined by the bacnetAlarmState property found on the point its connected to.

@param Dict[], bacnet alarm records Example:

finBacnetActiveAlarms([{alarmRecord}])

finBacnetCachedTemplateDiscovery ​

@Axon { admin=true } static Grid finBacnetCachedTemplateDiscovery(Obj broadcasAddress, Number low := Number.<ctor>(0), Number high := Number.<ctor>(4194303), Number discoveryTimeout := Number.<ctor>(8sec))

Performs the same operation as finBacnetTemplateDiscovery and caches the resulting discovery Grid for the next 15 minutes For clearing this cache call finBacnetClearCachedTemplateDiscovery

finBacnetClearCache ​

@Axon { admin=true } static Void finBacnetClearCache(Obj conn)

finBacnetClearCachedTemplateDiscovery ​

@Axon { admin=true } static Bool finBacnetClearCachedTemplateDiscovery()

Clear any previously cached template discovery

finBacnetConnStats ​

@Axon static Grid finBacnetConnStats(Obj rec)

Returns a Grid with various details about the BACnet connection and the device this connection is made to.

Usage:

finBacnetConnStats(@connRef)

finBacnetCreatEquip ​

@Axon { admin=true } static Grid finBacnetCreatEquip(Obj conn, Obj parentParam, Obj? uriParam := null, Obj? pointsParam := null)

Creates equipment, sub-equipment and points under each sub-equipment. The function will learn the object structure from the given BACnet connector by querying each object type specified in the uriParam. The default uriParam is null, that is all object types of this connector.

The pointsParam will specify a list of point string references, see bacnetCur. If the points specified don't fit in a uri parameter type then the point will not be placed under a sub-equipment but under the main device equipment.

The parentParam tells this function where the device equipment should be created in the nav tree. Valid parent nodes can be equip, floor or site.

Example:

// create device equipment and all sub-equips for the object types for a bacnetConn
finBacnetCreatEquip(@someBacnetConnRef, @someSiteRef)
// create device equipment and sub-equipments only for these types
finBacnetCreatEquip(@someBacnetConnRef, @someFloorRef, [`ANALOG_INPUT`, `BINARY_VALUE`])

Returns error grid on failure, otherwise a grid containing these columns:

subEquipCount: Number
pointCount: Number
equipRef:   Ref // the parent imported device equipment

finBacnetDiscoveryTags ​

@Axon { admin=true } static Dict[] finBacnetDiscoveryTags()

Gives the predefined set of tags, that will be used for a BACnet discovery. The tags need to be in a trio format and need to be placed in /bacnetProperties.trio in any template package. The tags can also be in a trio file uploaded to folio with a bacnetProperties tag. The tag specify which BACnet object properties need to be read from the discovered devices and their child objects.

Example bacnetProperties.trio:

---------------------------------------
object: "Device"
property: "vendor_name"
tagName: "vendorName"
---------------------------------------
object: "Binary_Value"
property: "object_name"
tagName: "objectName"
---------------------------------------
 object: "AV1"
 property: "present_value"
 tagName: "presentValue"

The function will read the specified property tags from the BACnet devices and objects and it will construct a grid with the property name mapped to the tagName value.

finBacnetFilterDevices ​

@Axon { admin=true } static Grid finBacnetFilterDevices(Grid devices)

Receives a list (as a grid) of bacnet devices and filters the ones that are not already added in the DB. It compares the uris.

finBacnetTemplateDiscovery ​

@Axon { admin=true } static Grid finBacnetTemplateDiscovery(Obj broadcasAddress, Number low := Number.<ctor>(0), Number high := Number.<ctor>(4194303), Number discoveryTimeout := Number.<ctor>(8sec), Number networkNumber := Number.<ctor>(65535))

Performs a BACnet discovery and reads the properties specified in the set of predefined tags. No filtering is done. The tags need to be in a trio format and need to be placed in /bacnetProperties.trio in any template pod file. The tags specify which BACnet object properties need to be read from the discovered devices and their child objects.

Example bacnetProperties.trio:

---------------------------------------
object: "Device"
property: "vendor_name"
tagName: "vendorName"
---------------------------------------
object: "Binary_Value"
property: "object_name"
tagName: "objectName"
---------------------------------------
 object: "AV1"
 property: "present_value"
 tagName: "presentValue"

The function will read the specified property tags from the BACnet devices and objects and it will construct a grid with the property name mapped to the tagName value.

Examples:

finBacnetTemplateDiscovery("255.255.255.255:47808")
// discover IP devices in the 1 - 100 range
finBacnetTemplateDiscovery("10.10.10.255", 1, 100)
// discover MS/TP devices in the 1 - 100 range
finBacnetTemplateDiscovery(`bacnetMstp://com1?baud=38400`, 1, 100)

finBacnetTemplateDiscoveryAdd ​

@Axon { admin=true } static Grid finBacnetTemplateDiscoveryAdd(List recordIds)

Adds the device records found in a discovery session and reads additional properties specified in the predefined template tags. The tags need to be in a trio format and need to be placed in /bacnetProperties.trio in any template pod file. The tags specify which BACnet object properties need to be read from the discovered devices.

Example bacnetProperties.trio:

---------------------------------------
object: "Device"
property: "vendor_name"
tagName: "vendorName"
---------------------------------------
object: "Binary_Value"
property: "object_name"
tagName: "objectName"
---------------------------------------
 object: "AV1"
 property: "present_value"
 tagName: "presentValue"

The function will read the specified property tags from the BACnet devices and it will add them to the discovery record.

Parameters:

  • recordIds: list of ids from the device records found in a discovery session

finBacnetTemplateDiscoveryPreview ​

@Axon { admin=true } static Grid finBacnetTemplateDiscoveryPreview(List recordIds)

This previews the connectors that will be made by the finBacnetTemplateDiscoveryAdd function.

Previews device records found in a discovery session and reads additional properties specified in the predefined template tags. The tags need to be in a trio format and need to be placed in /bacnetProperties.trio in any template pod file. The tags specify which BACnet object properties need to be read from the discovered devices.

Example bacnetProperties.trio:

---------------------------------------
object: "Device"
property: "vendor_name"
tagName: "vendorName"
---------------------------------------
object: "Binary_Value"
property: "object_name"
tagName: "objectName"
---------------------------------------
 object: "AV1"
 property: "present_value"
 tagName: "presentValue"

The function will read the specified property tags from the BACnet devices and it will add them to the discovery record.

Parameters:

  • recordIds: list of ids from the device records found in a discovery session

finBacnetTemplateRead ​

static Dict[] finBacnetTemplateRead(Dict[] devices, Bool includePoints, Bool separatePoints)

Read for the given devices, all the properties defined in the template pods. You can opt to include also the objects/points' properties defined in template pods.

finBacnetTemplates ​

@Axon { admin=true } static Dict[] finBacnetTemplates()

This is a replacement for the old SysLib.templates() function who's functionality has changed drastically. This function will generically find any pods that contains a </templates.trio> file.

finTemplateGenerateFunc ​

@Axon { admin=true } static Str? finTemplateGenerateFunc(Obj connId, Obj templId)

This is the logic that finTemplateOn uses to create the function to run on a template.

funcTemplate: sampleFunc($this, $vendorName)

Notice, the $ notation, those are auto-bind vars, $this is a special var that points to the current connId record, $vendorName binds to the current, filter matching connId, record's vendorName tag.

finTemplateOn ​

@Axon { admin=true } static Void finTemplateOn(Grid grid)

This will search for a templateOn tag in the current project and if the Filter expression matches records from the grid, then it will execute the funcTemplate tag expression on the matching record of the discovered grid.

Example templateOn rec:

templateOn: vendorName == "ACME Inc."
funcTemplate: sampleFunc($this, $vendorName)

Notice, the $ notation, those are auto-bind vars, $this is a special var that points to the current templateOn record, $vendorName binds to the current, filter matching templateOn, grid record's vendorName tag.

log ​

const static Log log := Log.get("finBacnet")

FinDeviceDiscoveryModel ​

class FinDeviceDiscoveryModel : DiscoveryModelChange

Constructors

make

Methods

addDevice
getDevices
updateDiscoveryInfoupdate any extra info that was read during discovery set the info on the devices dictionaries and update the device records

Slot Details ​

addDevice ​

virtual override Void addDevice(Obj?[]? items)

getDevices ​

virtual override Dict[] getDevices()

make ​

new make(Ref discoveryId, Context context)

updateDiscoveryInfo ​

virtual override Void updateDiscoveryInfo()

update any extra info that was read during discovery set the info on the devices dictionaries and update the device records

JobStatus ​

const class JobStatus : Obj

Constructors

make

Fields

job
name
progress

Slot Details ​

job ​

const Future? job

make ​

new make(Str name, Future? f, Int progress)

name ​

const Str name

progress ​

const Int progress

TemplateDiscoveryActor ​

const class TemplateDiscoveryActor : Actor

Constructors

make

Methods

log
receive

Slot Details ​

log ​

Log log()

make ​

new make(ActorPool p)

receive ​

virtual override Obj? receive(Obj? msg)

TemplateDiscoveryEntry ​

class TemplateDiscoveryEntry : Obj

Fields

grid
ts

Slot Details ​

grid ​

Grid? grid := null

ts ​

DateTime? ts := null

TemplateDiscoveryMsg ​

const class TemplateDiscoveryMsg : Obj

Constructors

make

Fields

dev
mustReadObjects
separateObjects

Methods

ctx
typePropTag
typeProps

Slot Details ​

ctx ​

Context ctx()

dev ​

const Dict dev

make ​

new make(Bool mustReadObjects, Bool separateObjects, Dict dev, Str:Str:BacStacPropertyIdentifier typeProps, Str:Str:BacStacPropertyIdentifier typePropTag, Context ctx)

mustReadObjects ​

const Bool mustReadObjects

separateObjects ​

const Bool separateObjects

typePropTag ​

Str:Str:BacStacPropertyIdentifier typePropTag()

typeProps ​

Str:Str:BacStacPropertyIdentifier typeProps()

TemplateDiscoveryResponse ​

const class TemplateDiscoveryResponse : Obj

Constructors

make

Fields

dev
rows

Slot Details ​

dev ​

const Dict dev

make ​

new make(Dict dev, Dict[] rows)

rows ​

const Dict[] rows