lib-conn 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793259180/FIN+5.3.1+lib-conn 中文整理基于 FIN 5.3.1

导读： 本页为 lib-conn 的 API / 标签 / 函数参考文档。

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

---

目录（导读）

• lib
• meta
• tags
• funcs
• views
• def
• supertypes
• subtypes
• tags
• usage
• enum
• connClose(conn)
• connDetails(obj)
• connLearn(conn, arg: null)
• connPing(conn)
• connPoints(conn, checked: true)
• connPointsVia(points, libOrConn)
• connSyncCur(points)
• connSyncHis(points, span: null)
• connTrace(conn, opts: null)
• connTraceClear(conn)
• connTraceDisable(conn)
• connTraceDisableAll()
• connTraceEnable(conn)
• connTraceIsEnabled(conn)
  • src

---

概述（中译）

连接器框架

---

API 正文（英文）

tags

actorTimeout	Timeout for messages send to the connector's actor thread
conn	Connector for communication to a remote system
connErr	Error message associated when connStatus indicates an error condition
connFeatures	Defines the features supported by a given connector
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connPoint	Point associated with a connector for data synchronization with a remote system
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuning	Marker applied to a rec which defines a tuning configuration
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
hisConvert	Conversion to apply when reading history data from connector
pointConvert	Point value conversion used to normalize data to/from a remote system
pollTime	Frequency between polls of curVal
staleTime	Time before a point's curStatus marked from "ok" to "stale" See Connector Tuning
writeConvert	Conversion to apply when writing writeVal to the connector
writeMaxTime	Maximum time between writes used to send periodic writes
writeMinTime	Minimum time between writes used to throttle the speed of writes
writeOnOpen	Issue a write every time the connector transitions from open to closed
writeOnStart	Issue a write when the system first starts up

---

funcs

connClose	Force the given connector closed and return a future
connDetails	Return debug details for a connector or a connector point
connLearn	Perform a learn on the given connector and return a future
connPing	Perform a ping on the given connector and return a future
connPoints	Return the points for a connector as list of dicts
connPointsVia	Select a group of points explicitly via specific connector library or connector
connSyncCur	Perform a remote sync of current values for the given points
connSyncHis	Perform a remote sync of history data for the given points
connTrace	Read a connector trace log as a grid
connTraceClear	Clear the trace log for the given connector
connTraceDisable	Disable tracing on the given connector
connTraceDisableAll	Disable tracing on every connector in the database
connTraceEnable	Enable tracing on the given connector
connTraceIsEnabled	Return true or false if given connector has its tracing enabled

---

views

connTrace	View debug connector tracing
connTuning	Manage connector tuning records in the local project database
conns	Manage connectors in the local project database

---

---

def

actorTimeout

Timeout for messages send to the connector's actor thread. It must be a number with a duration unit. If omitted a default of 1min is used. This value effectively determines how long a blocking remote request should take before raising a timeout error. For protocols which communicate via HTTP/TCP it is also used to configure the socket's receive timeout. See Connector Tuning

---

meta

def	actorTimeout
is	duration
lib	lib:conn
tagOn	conn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

conn

Connector for communication to a remote system. See Connectors

---

meta

def	conn
is	entity
lib	lib:conn
mandatory	✓

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier

---

subtypes

arcbeamConn	Arcbeam connector
ecobeeConn	Ecobee connector
energyStarConn	Energy Star connector to a portfolio manager account
haystackConn	Haystack connector to a Haystack REST API server
modbusConn	Modbus connector
mqttConn	MQTT connector to an MQTT Broker
nestConn	Google Nest connector
obixConn	Connector to an oBIX HTTP server
opcConn	Marker tag for OPC connector record which stores the configuration for connectivity to an OPC UA endpoint
sedonaConn	Sedona Sox connector to a remote device
snmpConn	SNMP connector
sqlConn	SQL connector to a relational database using JDBC
tplTrendConn	TplTrend connector

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
connErr	Error message associated when connStatus indicates an error condition
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
id	Defines the unique identifier of an entity in system using a ref value type

---

---

def

connErr

Error message associated when connStatus indicates an error condition. See Connectors

---

meta

def	connErr
is	str
lib	lib:conn
tagOn	conn
transient	✓

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

connFeatures

Defines the features supported by a given connector. This is a tag added to the conn def itself. The value is a dict with the following standardized keys:

• learn: marker tag if point learn is supported
• pollMode: manual or buckets

Also see Custom Connectors

---

meta

def	connFeatures
is	dict
lib	lib:conn

---

supertypes

val	Data value type
dict	Map of name/value tag pairs

---

---

def

connLinger

Linger timeout used to keep a connector open. If not configured then a default of 30sec is used. See Connector Tuning

---

meta

def	connLinger
is	duration
lib	lib:conn
tagOn	conn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

connOpenRetryFreq

Duration used for connector open retries. When a connector should be pinned opened for application use, then this frequency is used to periodically attempt retries. For example if a down connector has watched points, then this frequency is used to determine how often we retry to reopen the connection. The default is 10sec if not specified. See Connector Tuning

---

meta

def	connOpenRetryFreq
is	duration
lib	lib:conn
tagOn	conn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

connPingFreq

Duration used to configure the auto-ping feature on a given connector. When this tag is configured the connector will automatically attempt a ping based on the configured frequency. For connectors which might not have watched points this ensures periodic checks of the connectivity status. If this tag is not defined on a connector then the feature is disabled. See Connector Tuning

---

meta

def	connPingFreq
is	duration
lib	lib:conn
tagOn	conn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

connPoint

Point associated with a connector for data synchronization with a remote system.

---

meta

def	connPoint
is	point
lib	lib:conn

---

usage

connPoint  point

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator

---

subtypes

arcbeamPoint	Point which synchronizes data via a arcbeam connector
ecobeePoint	Point which synchronizes data via an Ecobee connector
haystackPoint	Point which synchronizes data via a Haystack connector
modbusPoint	Point which synchronizes data via a Haystack connector
mqttPoint	Point which synchronizes data via a MQTT connector
nestPoint	Point which synchronizes data via a Nest connector
obixPoint	Point which synchronizes data via a oBIX connector
opcPoint	Point which synchronizes data via an OPC connector
sedonaPoint	Point which synchronizes data via a Sedona connector
snmpPoint	Point which synchronizes data via an SNMP connector
sqlPoint	Point which synchronizes data via a SQL connector
tplTrendPoint	Point which synchronizes data via the TplTrend connector

---

tags

connTuningRef	Reference to a tuning configuration defined by a connTuning rec
cur	Supports current value
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
hisConvert	Conversion to apply when reading history data from connector
id	Defines the unique identifier of an entity in system using a ref value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with disMacro to create computed display strings
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

connState

Current connection state of a connector as one of the predefined strings. See Connectors

---

meta

def	connState
enum	See below
is	str
lib	lib:conn
tagOn	conn
transient	✓

---

enum

closed	Connection is closed
closing	Connection is currently being closed
open	Connection is open
opening	Connection is currently being opened

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

connStatus

Current status of a connector as one of the predefined strings See Connectors

---

meta

def	connStatus
enum	See below
is	str
lib	lib:conn
tagOn	conn
transient	✓

---

enum

ok	All is okay
fault	Configuration problem
down	Communication or network problem
disabled	Manual disable
unknown	Status not computed yet

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

connTuning

Marker applied to a rec which defines a tuning configuration. See Connector Tuning

---

meta

def	connTuning
is	entity
lib	lib:conn
mandatory	✓

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier

---

tags

dis	Display name for an entity
id	Defines the unique identifier of an entity in system using a ref value type
pollTime	Frequency between polls of curVal
staleTime	Time before a point's curStatus marked from "ok" to "stale" See Connector Tuning
writeMaxTime	Maximum time between writes used to send periodic writes
writeMinTime	Minimum time between writes used to throttle the speed of writes
writeOnOpen	Issue a write every time the connector transitions from open to closed
writeOnStart	Issue a write when the system first starts up

---

---

def

connTuningRef

Reference to a tuning configuration defined by a connTuning rec. See Connector Tuning

---

meta

def	connTuningRef
is	ref
lib	lib:conn
of	connTuning
tagOn	conn, connPoint, lib

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

---

---

def

curCalibration

Calibration value to apply to adjust the value read from the connector before updating curVal. The conversion is applied to the ConnPoint.updateCurOk value after curConvert is applied and before writing curVal to the database. See Connectors

---

meta

def	curCalibration
is	number
lib	lib:conn
tagOn	connPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit

---

---

def

curConvert

Conversion to apply when reading curVal from connector. The conversion is applied to the ConnPoint.updateCurOk value before applying curCalibration and writing curVal to the database. See Connectors

---

meta

def	curConvert
is	pointConvert
lib	lib:conn
tagOn	connPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters
pointConvert	Point value conversion used to normalize data to/from a remote system

---

---

def

func:connClose

connClose(conn)

Force the given connector closed and return a future. The future result is the connector rec dict. The conn parameter may be anything accepted by toRecId().

Examples:

read(conn).connClose
connClose(connId)

---

meta

admin	✓
def	func:connClose
is	func
lib	lib:conn
name	connClose

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connDetails

connDetails(obj)

Return debug details for a connector or a connector point. The argument is anything acceptable by toRecId(). The result is returned as a plain text string.

---

meta

admin	✓
def	func:connDetails
is	func
lib	lib:conn
name	connDetails

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connLearn

connLearn(conn, arg: null)

Perform a learn on the given connector and return a future. The future result is the learn grid. The conn parameter may be anything acceptable by toRecId(). The arg is an opaque identifier used to walk the learn tree via the learn column. Pass null for arg to return the root of the learn tree.

Examples:

connLearn(connId, learnArg)

---

meta

admin	✓
def	func:connLearn
is	func
lib	lib:conn
name	connLearn

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connPing

connPing(conn)

Perform a ping on the given connector and return a future. The future result is the connector rec dict. The conn parameter may be anything accepted by toRecId().

Examples:

read(conn).connPing
connPing(connId)

---

meta

admin	✓
def	func:connPing
is	func
lib	lib:conn
name	connPing

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connPoints

connPoints(conn, checked: true)

Return the points for a connector as list of dicts. The conn parameter may be anything accepted by toRecId(). If conn cannot be be mapped to an active connector then raise an exception or return an empty list based on checked flag.

Examples:

read(haystackConn).connPoints
connPoints(@my-conn-id)

---

meta

def	func:connPoints
is	func
lib	lib:conn
name	connPoints

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connPointsVia

connPointsVia(points, libOrConn)

Select a group of points explicitly via specific connector library or connector. This function is required when points are associated with multiple connectors. Pass a connector library name to select for a protocol. Or pass a connector id/rec to select via a specific connector. Also see Connectors.

Examples:

// explicitly sync via the SQL connector library
readAll(sqlConnRef).connPointsVia("sql").connSyncHis

// get debug details for specific connector
connPointsVia(pt, pt->bacnetConnRef).connDetails

---

meta

admin	✓
def	func:connPointsVia
is	func
lib	lib:conn
name	connPointsVia

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connSyncCur

connSyncCur(points)

Perform a remote sync of current values for the given points. The points parameter may be anything acceptable by toRecIdList(). Return a list of futures for each unique connector. The result of each future is unspecified. Also see Connectors.

Examples:

readAll(bacnetCur).connSyncCur

---

meta

admin	✓
def	func:connSyncCur
is	func
lib	lib:conn
name	connSyncCur

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connSyncHis

connSyncHis(points, span: null)

Perform a remote sync of history data for the given points. The points parameter may be anything acceptable by toRecIdList(). The span parameter is anything acceptable by toSpan(). Or pass null for span to perform a sync for items after the point's hisEnd. This blocks the calling thread until each point is synchronized one by one. Normally it should only be called within a task. The result from this function is undefined. Also see Connectors.

Examples:

readAll(haystackHis).connSyncHis(null)

---

meta

admin	✓
def	func:connSyncHis
is	func
lib	lib:conn
name	connSyncHis

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTrace

connTrace(conn, opts: null)

Read a connector trace log as a grid. If tracing is not enabled for the given connector, then an empty grid is returned. The conn parameter may be anything acceptable by toRecId().

Examples:

read(conn).connTrace
connTrace(connId)

---

meta

admin	✓
def	func:connTrace
is	func
lib	lib:conn
name	connTrace

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTraceClear

connTraceClear(conn)

Clear the trace log for the given connector. The conn parameter can be anything acceptable by toRecId().

---

meta

admin	✓
def	func:connTraceClear
is	func
lib	lib:conn
name	connTraceClear

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTraceDisable

connTraceDisable(conn)

Disable tracing on the given connector. The conn parameter can be anything acceptable by toRecId().

---

meta

admin	✓
def	func:connTraceDisable
is	func
lib	lib:conn
name	connTraceDisable

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTraceDisableAll

connTraceDisableAll()

Disable tracing on every connector in the database.

---

meta

admin	✓
def	func:connTraceDisableAll
is	func
lib	lib:conn
name	connTraceDisableAll

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTraceEnable

connTraceEnable(conn)

Enable tracing on the given connector. The conn parameter can be anything acceptable by toRecId().

---

meta

admin	✓
def	func:connTraceEnable
is	func
lib	lib:conn
name	connTraceEnable

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:connTraceIsEnabled

connTraceIsEnabled(conn)

Return true or false if given connector has its tracing enabled. The conn parameter can be anything acceptable by toRecId().

---

meta

admin	✓
def	func:connTraceIsEnabled
is	func
lib	lib:conn
name	connTraceIsEnabled

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

hisConvert

Conversion to apply when reading history data from connector. The conversion is applied to each item passed to ConnPoint.updateHisOk before writing to the database. This conversion happens before the hisOnWrite conversion hooks. See Connectors

---

meta

def	hisConvert
is	pointConvert
lib	lib:conn
tagOn	connPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters
pointConvert	Point value conversion used to normalize data to/from a remote system

---

---

def

pointConvert

Point value conversion used to normalize data to/from a remote system. See Connectors

---

meta

def	pointConvert
is	str
lib	lib:conn

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

subtypes

curConvert	Conversion to apply when reading curVal from connector
hisConvert	Conversion to apply when reading history data from connector
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

pollTime

Frequency between polls of curVal. See Connector Tuning.

---

meta

def	pollTime
is	duration
lib	lib:conn
tagOn	connTuning

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

staleTime

Time before a point's curStatus marked from "ok" to "stale" See Connector Tuning.

---

meta

def	staleTime
is	duration
lib	lib:conn
tagOn	connTuning

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

view:connTrace

View debug connector tracing

---

meta

admin	✓
appName	conn
def	view:connTrace
disKey	ui::trace
icon	view
is	view
lib	lib:conn
order	110

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:    { uiType:"uiBuilder::ConnTraceView" }
conn:    { input var kind:"Ref<conn>" }
types:   { input var kind:"Str" defVal:"phase,dispatch,req,res,event,log" uiInput:"uiBuilder::ConnTraceTypesInput" }
ping:    { action:"connPing" select noFlash }
close:   { action:"connClose" select noFlash }
enable:  { action:"connTraceEnable" select noFlash }
disable: { action:"connTraceDisable" select noFlash }
clear:   { action:"connTraceClear" select noFlash }
menu:    { action:"uiContextMenu" selInput:"conn"}
details: { action:"connBuilderDetails" select }
data:    { expr:"connTrace({{conn}}, {types:{{types}}})" }

---

---

def

view:connTuning

Manage connector tuning records in the local project database

---

meta

admin	✓
appName	conn
def	view:connTuning
defName	connTuning
disKey	ui::tuning
icon	view
is	view
lib	lib:conn
order	105

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:    { inherit:"table" }
search:  { input var kind:"Str" defVal:"" }
new:     { action:"recNew" }
edit:    { action:"recEdit" }
trash:   { action:"recTrash" }
data:    { expr:"readAll(connTuning, { sort, search:{{search}} })" }

---

---

def

view:conns

Manage connectors in the local project database

---

meta

admin	✓
appName	conn
def	view:conns
disKey	ui::connector
icon	view
is	view
lib	lib:conn
order	100

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view: { uiType:"uiBuilder::ConnBuilder" }
menu: { action:"uiContextMenu" }

---

---

def

writeConvert

Conversion to apply when writing writeVal to the connector. The conversion is applied to writeVal before calling ConnDispatch.onWrite. See Connectors

---

meta

def	writeConvert
is	pointConvert
lib	lib:conn
tagOn	connPoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters
pointConvert	Point value conversion used to normalize data to/from a remote system

---

---

def

writeMaxTime

Maximum time between writes used to send periodic writes. See Connector Tuning.

---

meta

def	writeMaxTime
is	duration
lib	lib:conn
tagOn	connTuning

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

writeMinTime

Minimum time between writes used to throttle the speed of writes. See Connector Tuning.

---

meta

def	writeMinTime
is	duration
lib	lib:conn
tagOn	connTuning

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
number	Integer or floating point numbers annotated with an optional unit
duration	Number with a unit of time

---

---

def

writeOnOpen

Issue a write every time the connector transitions from open to closed. See Connector Tuning.

---

meta

def	writeOnOpen
is	marker
lib	lib:conn
tagOn	connTuning

---

supertypes

marker	Marker labels a dict with typing information

---

---

def

writeOnStart

Issue a write when the system first starts up. If missing then the first write is suppressed on startup. See Connector Tuning.

---

meta

def	writeOnStart
is	marker
lib	lib:conn
tagOn	connTuning

---

supertypes

marker	Marker labels a dict with typing information