lib-arcbeam 库参考

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

导读： Arcbeam 连接器扩展

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

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• views
• def
• usage
• supertypes
• tags
• Overview
• Setup
• Advantages
• Reverse Proxy
• Niagara Arcbeam
• arcbeamCall(conn, name, args: [,])
• arcbeamEval(conn, expr)
• arcbeamRead(conn, filterExpr, checked: true)
• arcbeamReadAll(conn, filterExpr, opts: null)
• arcbeamReadById(conn, id, checked: true)
• arcbeamReadByIds(conn, ids, checked: true)
  • src

---

概述（中译）

Arcbeam 连接器扩展

---

API 正文（英文）

docs

Overview • Setup • Advantages • Reverse Proxy • Niagara Arcbeam

---

tags

arcbeamConn	Arcbeam connector
arcbeamConnRef	Used on a proxy point to reference its parent arcbeamConn
arcbeamCur	Used on a arcbeam proxy point to store the id of the entity in the remote system used to read and watch curVal
arcbeamHis	Used on a arcbeam proxy point object to store the id of the historized point in the remote system used to sync history data
arcbeamMinEventTime	Applied to arcbeamConn to tune how fast the server should send current value updates
arcbeamPoint	Point which synchronizes data via a arcbeam connector
arcbeamWrite	Used on a arcbeam proxy point to store the id of the entity in the remote system used to write writeVal
arcbeamWriteLevel	Number between 1 and 16 used with arcbeamWrite to determine which priority level of the remote system is written to

---

funcs

arcbeamCall	Evaluate a platform specific operation on the remote node
arcbeamEval	Evaluate a platform specific expression on the remote node
arcbeamRead	Read a single record from remote node with filter and return as a dict
arcbeamReadAll	Read a grid of records from remote node with a filter
arcbeamReadById	Read a record from the remote node by its unique id and return as dict
arcbeamReadByIds	Read a list of records from remote node by their identifiers

---

views

arcbeamNodes	Project database of arcbeam connector nodes

---

---

def

arcbeamConn

Arcbeam connector

---

meta

connFeatures
def	arcbeamConn
icon	arcbeam
is	conn
lib	lib:arcbeam

---

usage

arcbeamConn  conn

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
conn	Connector for communication to a remote system

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
arcbeamMinEventTime	Applied to arcbeamConn to tune how fast the server should send current value updates
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
isolate	Isolate this node from making inbound requests
nodeId	Node id as string without the n: prefix
pubKey	Public key as encoded string
uri	Universal resource identifier

---

---

def

arcbeamConnRef

Used on a proxy point to reference its parent arcbeamConn

---

meta

def	arcbeamConnRef
is	ref
lib	lib:arcbeam
of	arcbeamConn
tagOn	arcbeamPoint

---

supertypes

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

---

---

def

arcbeamCur

Used on a arcbeam proxy point to store the id of the entity in the remote system used to read and watch curVal.

---

meta

def	arcbeamCur
is	str
lib	lib:arcbeam
tagOn	arcbeamPoint

---

supertypes

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

---

---

def

arcbeamHis

Used on a arcbeam proxy point object to store the id of the historized point in the remote system used to sync history data.

---

meta

def	arcbeamHis
is	str
lib	lib:arcbeam
tagOn	arcbeamPoint

---

supertypes

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

---

---

def

arcbeamMinEventTime

Applied to arcbeamConn to tune how fast the server should send current value updates.

---

meta

def	arcbeamMinEventTime
is	duration
lib	lib:arcbeam
tagOn	arcbeamConn
val	1sec

---

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

arcbeamPoint

Point which synchronizes data via a arcbeam connector.

---

meta

def	arcbeamPoint
is	connPoint
lib	lib:arcbeam

---

usage

arcbeamPoint  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
connPoint	Point associated with a connector for data synchronization with a remote system

---

tags

arcbeamConnRef	Used on a proxy point to reference its parent arcbeamConn
arcbeamCur	Used on a arcbeam proxy point to store the id of the entity in the remote system used to read and watch curVal
arcbeamHis	Used on a arcbeam proxy point object to store the id of the historized point in the remote system used to sync history data
arcbeamWrite	Used on a arcbeam proxy point to store the id of the entity in the remote system used to write writeVal
arcbeamWriteLevel	Number between 1 and 16 used with arcbeamWrite to determine which priority level of the remote system is written to
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

arcbeamWrite

Used on a arcbeam proxy point to store the id of the entity in the remote system used to write writeVal.

---

meta

def	arcbeamWrite
is	str
lib	lib:arcbeam
tagOn	arcbeamPoint

---

supertypes

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

---

---

def

arcbeamWriteLevel

Number between 1 and 16 used with arcbeamWrite to determine which priority level of the remote system is written to.

---

meta

def	arcbeamWriteLevel
defVal	16
is	int
lib	lib:arcbeam
maxVal	16
minVal	1
tagOn	arcbeamPoint

---

supertypes

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

---

lib arcbeam

Overview

The Arcbeam extension implements a full connector using the arcbeam protocol which is also used for clustering. The Arcbeam connector supports the full suite of connector functionality including:

• Learn tree navigation
• Current value one-time syncs via connSyncCur()
• Current value subscriptions for change-of-value updates
• History sync via connSyncHis()
• Point writes

Setup

The Arcbeam connector only runs in SkySpark and requires active maintenance. You may connect to any of the following systems:

• Another SkySpark project running the arcbeam extension
• A Haxall node with an enabled cluster extension
• A Niagara node with the "arcbeam-rt.jar" installed (see Niagara Setup section)

In SkySpark the node URI is ws://{host}:{port}/api/{proj} (or wss: if using TLS). Note that unlike cluster you must specify the project name in the URI.

Advantages

Using arcbeam for a connector provides several advantages over other protocols such as Haystack:

• Flexibility to tunnel through firewalls
• WebSocket avoids TCP/HTTP overhead on each message
• Binary message encoding (Brio) is more efficient

Reverse Proxy

If SkySpark is deployed behind a reverse proxy, such as Nginx, then additional configuration is required for arcbeam connections.

For Nginx, a new location block can be added for the project where the arcbeam extension is enabled:

location = /api/{projname}/ { #UPDATE PROJECT NAME
  proxy_pass http://skyspark.local:8080; #UPDATE LOCAL SKYSPARK ADDRESS/PORT
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $http_connection;
  proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol;
}

Alternatively, the default location can be updated:

location / {
  proxy_pass http://skyspark.local:8080; #UPDATE LOCAL SKYSPARK ADDRESS/PORT
  proxy_set_header Host $host;
  proxy_http_version 1.1;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-Proto http;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $http_connection;
  proxy_set_header Sec-WebSocket-Protocol $http_sec_websocket_protocol;
}

Niagara Arcbeam

SkyFoundry supports an Arcbeam integration with the Niagara Framework. Please refer to the Niagara Arcbeam App Note for more information.

---

---

def

func:arcbeamCall

arcbeamCall(conn, name, args: [,])

Evaluate a platform specific operation on the remote node.

For SkySpark and Haxall nodes, this will remotely evaluate an Axon function using the same semantics as the call() function. The the current local user is used on the remote node.

Niagara nodes support a specific set of calls discussed in the Niagara Arcbeam docs. Note that Niagara nodes do not support Haystack ops.

Examples:

// Haxall node
arcbeamCall(@conn, "about")

---

meta

admin	✓
def	func:arcbeamCall
is	func
lib	lib:arcbeam
name	arcbeamCall

---

supertypes

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

---

---

def

func:arcbeamEval

arcbeamEval(conn, expr)

Evaluate a platform specific expression on the remote node.

For SkySpark and Haxall nodes, this will remotely evaluate an Axon expression. The the current local user is used on the remote node.

Examples:

arcbeamEval(@conn, "readAll(equip)")

---

meta

admin	✓
def	func:arcbeamEval
is	func
lib	lib:arcbeam
name	arcbeamEval

---

supertypes

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

---

---

def

func:arcbeamRead

arcbeamRead(conn, filterExpr, checked: true)

Read a single record from remote node with filter and return as a dict. If not found, then return null or raise UnknownRecErr based on checked flag.

Examples:

arcbeamRead(@conn, ahu and equip)

---

meta

admin	✓
def	func:arcbeamRead
is	func
lib	lib:arcbeam
name	arcbeamRead

---

supertypes

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

---

---

def

func:arcbeamReadAll

arcbeamReadAll(conn, filterExpr, opts: null)

Read a grid of records from remote node with a filter.

Supported options for all remote node types:

• limit: Number for max number of results

Supported Niagara Options

Examples:

arcbeamReadAll(@conn, ahu and equip)
arcbeamReadAll(@conn, ahu and equip, {limit:10})

---

meta

admin	✓
def	func:arcbeamReadAll
is	func
lib	lib:arcbeam
name	arcbeamReadAll

---

supertypes

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

---

---

def

func:arcbeamReadById

arcbeamReadById(conn, id, checked: true)

Read a record from the remote node by its unique id and return as dict. If the record is not found, then return null or raise UnknownRecErr based on checked flag.

Examples:

arcbeamReadById(@conn, @xyx-123)

---

meta

admin	✓
def	func:arcbeamReadById
is	func
lib	lib:arcbeam
name	arcbeamReadById

---

supertypes

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

---

---

def

func:arcbeamReadByIds

arcbeamReadByIds(conn, ids, checked: true)

Read a list of records from remote node by their identifiers. Return a grid where each row of the grid maps to the respective id list (indexes line up). If checked is true and any one of the ids cannot be resolved then raise UnknownRecErr for first id not resolved. If checked is false, then each id not found has a row where every cell is null.

Examples:

arcbeamReadByIds(@conn, [@abc-123, @xyx-123])

---

meta

admin	✓
def	func:arcbeamReadByIds
is	func
lib	lib:arcbeam
name	arcbeamReadByIds

---

supertypes

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

---

---

def

view:arcbeamNodes

Project database of arcbeam connector nodes

---

meta

admin	✓
appName	conn
def	view:arcbeamNodes
disKey	ui::arcbeam
icon	view
is	view
lib	lib:arcbeam

---

supertypes

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

---

src

view:       {inherit:"table"}
local:      {action:"arcbeamLocal" uiInput:"uiMisc::ClusterActions.local"}
hubDebug:   {dis:"Hub Debug" action:"arcbeamHubDebug"}
nodeDebug:  {dis:"Node Debug" action:"arcbeamNodeDebug" select}
watchDebug: {dis:"Watch Debug" action:"arcbeamWatchDebug" select}
new:        {action:"arcbeamNew"}
edit:       {action:"recEdit" defName:"arcbeamConn"}
trash :     {action:"recTrash"}
enable:     {action:"recEnable"}
disable:    {action:"recDisable"}
approve:    {action:"arcbeamApprove" select}
data:       {expr:"arcbeamNodes()"}