Conn (Connector) Flashcards
Conn Overview
The ConnExt provides the connector framework and its APIs. This framework entails:
- standardizes conventions for modeling connectors to remote systems
- standardizes connector status: ok, down, fault, disabled
- standardizes connector operations: open, close, ping, syncPoint, syncHis, etc
- standardizes point “cur” real-time synchronization and watches
- standardizes writable points
- standardizes point “his” historical data synchronization
- implements concurrency and lifecycle model
- provides simple callback mechanism for connector implementations
- defines standard Fresco app model and tabs
The connector framework provides significant infrastructure to ensure that integration to remote systems is easy to implement by software developers. But more importantly it provides a set of conventions to ensure that connectors provide uniformity for system integrators who deploy them on projects.
Conn Naming Conventions
The connector framework relies heavily on naming conventions. Everything starts with your extensions name. For example if you are developing a extension named “foo”, then the following names would be used:
foo ext/connector name fooExt ext pod name fooConn marker tag for connector rec fooConnRef tag applied to points to associated them with a connector fooCur point address tag for real-time synchronization fooWrite point address tag for writing to an output fooHis point address tag for history synchronization fooPing function to ping connector fooSyncCur function to sync curVal of points fooSyncHis function to sync history of points fooLearn function for discovery and learn mapping FooExt class name of connExt::ConnImplExt subclass FooConn class name of connExt::Conn subclass FooModel class name of connExt::ConnModel subclass
All of these names are generated automatically and accessible via the ConnModel class.
ConnIMpIExt
ConnImplExt
All connectors will create a normal their Ext by subclassing from ConnImplExt:
- base class handles start/stop lifecycle
- base class handles managing your connector map and their actors
- connector
actor lookup - the constructor will take your ConnModel
ConnModel
ConnModel
All connectors must create subclass of ConnModel which defines their tag names, func names, and capabilities:
- used by ConnImplExt and ConnApp
- all tag/func names derived using standard naming conventions
- override
ConnModel.isPollingSupportedto return true if supported - override
ConnModel.isLearnSupportedto return true if supported - override
ConnModel.isCurSupportedto return true if supported - override
ConnModel.isWriteSupportedto return true if supported - override
ConnModel.isHisSupportedto return true if supported - override
ConnModel.pointAddrTypeto return address type if your connector uses Uri or Number instead of Str
ConnLib
ConnLib
All connectors will create a FooLib class which defines their Axon functions. There is no base class for this, but your library class must use the normal extension pattern. A specific set of functions should be defined which will map directly to methods in the framework:
-
fooPing(conn):ConnActor.ping -
fooSyncCur(points):ConnImplExt.syncCur -
fooSyncHis(points):ConnImplExt.syncHis -
fooLearn(conn, arg):ConnActor.learn
ConnActor
ConnActor
Every connector rec defined in the database is mapped to to exactly one ConnActor. Each actor wraps one Conn instance which is responsible for managing all mutable state and networking to the remote system.
All messages to the Conn are sent as ConnMsg which is designed to allow implementations to perform their own messaging. Each of your messages should use a unique string identifier so that you don’t interfere with the built-in messages.
All messaging to the ConnActor uses a coalesing queue. For example if you send 100 ping messages and the actor is busy, they will coalesce into one single ping message. Coalescing is determined by ConnMsg.equals which in turn is determined by equality of the message arguments.
Conn
Conn
Every connector must define a subclass of Conn which is the heart of the framework; it is a mutable class which models the state, networking, and points of a fooConn record. As a mutable class, all state is managed within a ConnActor and other actors/threads communicate with yourConn via messaging.
Conn Accessors
Conn Accessors
Conn provides many accessor methods to environment:
-
Conn.ext: reference to yourConnImplExtinstance -
Conn.proj: reference to project database -
Conn.actor: actor used to manage all messaging to yourConn -
Conn.rec: current state of your connector record -
Conn.id: connector record id -
Conn.dis: convenience forrec.dis -
Conn.log: debugging and error logging
Conn Lifecycle Callbacks
Conn Lifecycle Callbacks
All the connector and point life cycle operators map to callbacks on this class. All of the following callbacks are make on the ConnActor thread:
-
Conn.onOpen: open network connection to device which results in a) successful communication, b) your subclass raises anDownErrif there is a communication error, or c) raisesFaultErrif configuration problem -
Conn.onClose: gracefully close down connection -
Conn.onPing: perform simple round trip communication with remote system and return metadata tags like device make, model, version -
Conn.onHouseKeeping: callback to periodically check background tasks (called every few seconds) -
Conn.onDiff: when connector record is modified -
Conn.onDelete: when connector record is removed from database -
Conn.onLearn: callback for yourfooLearnAxon function which is used by FooApp | Learn tab
Conn Point Callbacks
Conn Point Callbacks
The following callbacks are made on Conn to support its associated points:
-
Conn.onPoll: callback by poll scheduler -
Conn.onSyncCur: synchronizecurValfor a batch of points -
Conn.onSyncHis: synchronize history items for a single point and date range -
Conn.onWatch: callback when batch of points put into watch -
Conn.onUnwatch: callback when batch of points put taken out of watch -
Conn.onWrite: callback when writable point’s output command has been updated
Points are discussed further in under ConnPoint
Conn State
Conn State
A connector is in the opening, open, closing, or closed state indicated by the connState tag. These methods are used to manage a connector’s open state:
-
Conn.openLinger: open connector and leave it open for a linger period (default 30sec). After linger period if no one else has requested the connector open it automatically closes -
Conn.openPin: pin the connector open for a specific application; for example if there is ongoing data logging we want to keep the connector open all the time. A string key is used to indicate which application wishes the connector open. -
Conn.closePin: pinned apps must call this method with their string key when done. When all pinned applications are closed and there no linger, then the connector is closed down. -connExt::Conn.close: by default linger timeout andclosePinare used to control closing of the connector. But if a communication failure or some other event is detected which indicates the connector is down, then they should callclosewith the exception
When the an open is first requested, your Conn.onOpen callback is invoke. If onOpen throws an exception, then connStatus and connErr are updated based on the exception type (use DownErr to indicate a communication failure). If onOpen returns without raising an exception then connStatusis set to “ok”.
Your connector should establish connectivity during the onOpen callback. This might be establishing a TCP or session if your connector is session oriented. Or might just be a ping if using UDP or stateless protocol such as HTTP.
If your connector is disabled, then all callbacks are by-passed and status is forced to “disabled”.
Conn Learn
Conn Learn
The learn feature is used to “walk” the external system native data model and learn which points are available. to add learn to your connector you should create an Axon function called fooLearnwhich routes to ConnActor.learn. This in turn results in the Conn.onLearn callback.
The learn argument is an connector specific identifier used to keep of track of position within the tree or graph of the remote system data model. The null argument indicates learn at the root learn. Each call to learn takes the argument and returns a grid of the items at that level of the tree in the external system. If an item may be navigated into, then it should define its own learn identifier in the learn column. The ConnApp Learn tab uses the data to implement navigation of the external system via your Axon learn function.
If a learn item supports mapping to a point, then your resulting grid should include standard point data like fooCur, fooWrite, fooHis, kind, unit, etc. See Conn.onLearn for further details.
ConnPoint
ConnPoint
The ConnPoint is a mutable class used to keep track of state per point. ConnPoint is not subclassed by implementations, but you can stash a implementation specific object inConnPoint.data.
The Conn base class automatically keeps track of all a connector’s points associated by thefooConnRef. Each rec is wrapped by a ConnPoint instance. The following methods are used to work with a connector’s point list:
-
Conn.point: lookup a point by its record id -
Conn.points: list of all points -
Conn.pointsWatched: list of all points currently in a watch -
Conn.hasPointsWatched: are any connector’s point currently in a watch
ConnPoint Cur
ConnPoint Cur
Standard behavior of current value subscription is defined by pointExt.
Current value is synchronized once by the fooSyncCur function which results in theConn.onSyncCur callback. This callback works with a batch of points. If your protocol supports batch reads, then typically it most efficient to sync entire batch.
Continous synchronization of current value is managed when the point is put into a watch. Watch state is managed by the callbacks Conn.onWatch and Conn.onUnwatch. Both callbacks work with a batch of points. Typically there are two watch strategies:
- if the protocol supports change of value subscriptions, then watch/unwatch maps to subscribe/unsubscribe messages
- if the protocol does not support subscriptions, then your connector should use poll scheduler to periodically poll all
points in watch
The poll scheduler is enabled by ConnModel.isPollingSupported which automatically schedules the Conn.onPoll callback. The poll frequency is determined by the Conn.pollFreq method. By convention polling should be configured on a per connector basis using a tag called fooPollFreqor fallback to suitable default.
There are many ways that your points will end up synchronizing their current value:
- one time
onSyncCurread - initial subscription from
onWatch - async message from subscription change event
- read during
onPoll
In all cases if the current value is read successfully, then the connector should callConnPoint.updateCurOk with the SkySpark representation of the current value. If an error is detected such as a bad address, then ConnPoint.updateCurErr should be called. These methods manage the curVal, curStatus, and curErr tags for you automatically.
As a general principle, if there is an exception reading a point then call updateCurErr with the exception. The following exceptions type should be used for special cases:
-
FaultErr: connector is communicating correctly, but there is a configuration error with the point -
RemoteStatusErr: remote point can be read correctly, but the remote system status is not “ok”. For example if the remote point is “disabled”, then use this exception to set the local point into “remoteDisabled”
ConnPoint Writes
ConnPoint Writes
The standard behavior of writable points is defined by pointExt. The pointExt manages the 16-level priority array and calculates when a new command should be written by the connector - this results in the Conn.onWrite callback. Your callback should write the new value to the remote system, and then call ConnPoint.updateWriteOk or ConnPoint.updateWriteErr.
Connector library do not need to define any functions for writing. Writes are controlled by the standard point functions such as pointOverride and pointAuto.
ConnPoint His
ConnPoint His
If the connector’s protocol support history time-series data synchronization, then it should declare an axon function calls fooSyncHis which takes a list of points and a date range. The Axon function should route to ConnImplExt.syncHis which manages the nasty details for you:
- mapping points to records by connector
- mapping date range to actual
DateTimeSpan - iterating through each connector with proper job status and logging
The result is a series of calls to the Conn.onSyncHis callback which your connector should use to fetch the history items for the given date range. Your callback must then call updateHisOk with latest data or else call updateHisErr if there is an error. The framework automatically handles writing to the historian and managing your hisStatus and hisErr tags.
Tuning
Tuning
The ConnTuning class models the options used to tune the functionality of the connector points.
Tuning configurations are created as a rec in the Folio database with the connTuning tag.
Points are assigned to a tuning configuration via the connTuningRef tag. This tag is searched in the following order:
- Point rec itself
- Point’s connector rec
- Connector’s
extrec - Fallback to default tuning
The standard tuning options supported by the connector framework are detailed below. In addition, connector’s may use the tuning framework for their own custom options.
Note: all the tuning timers rely on periodic background processing which is only accurate to within 5 to 10sec.
pollTime
pollTime
The pollTime tag specifies a duration Number which is the frequency used to poll a point forcurVal. This tag is only used for connectors which support polling for their current value. Connectors which use a COV subscription model will ignore this value. If unspecified the default is 10sec.
staleTime
staleTime
The staleTime tag specifies a duration Number used to transition a point’s curStatus tag from “ok” to “stale”. It ensures that users and applications are aware that data might not be fresh. The transition to stale occurs when all the following conditions are met:
- the point’s
curStatusis currently “ok” - the point is not in a watch
- the last successful read exceeds the stale time
Note that we assume points in a watch are currently up-to-date even if their last read time exceeds the stale time. This is because change of value subscriptions might not be callingupdateCurOk continuously if no changes are received. If unspecified the default is 5min.
writeMinTime
writeMinTime
The writeMinTime tag specifies a duration Number used to throttle the frequency of writes to the remote device. For example if configured to 5sec, then writes will be issued no faster than 5sec. After a successful write occurs, if any writes are attempted within that 5sec window then they are queued as a pending write. After 5sec has elapsed the last pending write is issued to the connector’s onWrite callback. Note that writeMinTime is only enforced after successful writes. If the connector reports a write failure, then writeMinTime is not enforced on subsequent attempts.
writeMaxTime
writeMaxTime
The writeMaxTime tag specifies a duration Number used to issue periodic rewrites to the remote device. For example if configured to 10min, then if no successful writes have been issued after 10min then a write is automatically scheduled to the connector’s onWrite callback. The writeMaxTime does not go into effect until after the project reaches steady state.
Point Conversions
Point Conversions
The following tags are used to configure conversions between the normalized SkySpark representations and the connector’s remote device:
-
curConvert: converts from raw read value to curVal -
curCalibration: adjusts value before reading to curVal -
writeConvert: converts writeVal to raw value to write -
hisConvert: converts history items values from connector
The conversion is specified as a string using the point convert syntax.
For example if reading a temperature sensor we might apply a thermistor table to convert the raw sensor value into a normalized representation of Fahrenheit or Celsius degrees:
curConvert: "thermistor(10k-2)"
If the sensor needs calibration, we might further decide to adjust plus or minus a few degrees. If for example we wanted to add 2°F to the value being read from the sensor then:
curConvert: "thermistor(10k-2)" curCalibration: 2°F
ConnApplet
ConnApplet
The connector framework defines a standard app and allows connectors to plugin into the app by subclassing ConnApplet.
actor
actor
const ConnActor actor
Actor used to manage async processing of this connector
