lib-modbus 库参考

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

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

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

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• views
• Overview
• Supported Protocols
  • TCP/IP
  • RTU over TCP/IP
• Register Map
  • Addressing
  • Ping
  • Data Type
  • Read/Write
  • Scale Factor
  • Dis, Unit, Tags
• Current Points
• Writable Points
• History
• Block Reads
  • modbusBlockGap
  • modbusBlockMax
  • def
• modbusLearn(conn, arg: null)
  • supertypes
• modbusPing(conn)
• modbusRead(conn, regs)
• modbusRegMap(name)
• modbusRegMaps()
• modbusSyncCur(points)
• modbusWrite(conn, reg, val)
  • usage
  • tags
  • src

---

概述（中译）

Modbus 连接器

---

API 正文（英文）

docs

Overview • Supported Protocols • Register Map • Current Points • Writable Points • History • Block Reads

---

tags

modbusBlockGap	Applied to modbusConn to allow for gaps in block reads
modbusBlockMax	Applied to modbusConn to limit the maximum number of registers to read in a block read
modbusConn	Modbus connector
modbusConnRef	Used on a proxy point to reference its parent modbusConn
modbusCur	Modbus address to use for current value subscriptions
modbusPoint	Point which synchronizes data via a Haystack connector
modbusReadTimeout	How long to wait before timing out on a modbus read
modbusRegMapUri	Applied to modbusConn to define the register map CSV file
modbusSlave	Applied to modbusConn to identify the slave address on this modbus network
modbusWrite	Used on a modbus proxy point to store the id of the entity in the remote system used to write writeVal
modbusWriteTimeout	How long to wait before timing out on a modbus write

---

funcs

modbusLearn	Deprecated - use connLearn()
modbusPing	Deprecated - use connPing()
modbusRead	Read a point value for given register name on connector instance
modbusRegMap	Return given register map contents
modbusRegMaps	List installed register maps including source
modbusSyncCur	Deprecated - use connSyncCur()
modbusWrite	Write a value to given register name on connecter instance

---

views

modbusRegMap	Manage Modbus register map files

---

lib modbus

Overview

The ModbusExt implements connector support for Modbus protocol.

Supported Protocols

ModbusExt supports two protocols for accessing Modbus slave devices:

TCP/IP

To setup a connector to access a Modbus slave over TCP/IP, we use the modbus-tcp URI scheme:

dis: "Modbus TCP/IP Connector"
conn
modbusConn
uri: `modbus-tcp://host/`
modbusSlave: 1
modbusRegMapUri: `data/modbus/xxx.csv`

RTU over TCP/IP

To access the slave using serial RTU over a TCP connection, use the modbus-rtutcp scheme:

dis: "Modbus RTU over TCP/IP Connector"
conn
modbusConn
uri: `modbus-rtutcp://host/`
modbusSlave: 1
modbusRegMapUri: `data/modbus/xxx.csv`

Register Map

Modbus connectors are required to define a register map using the modbusRegMapUri tag. The register map specifies which points get read/written out of a Modbus slave. The register map URI must be a path relative to the project's home directory or can be a fan:// URI to a CSV file bundled in a pod.

Register maps are simple CSV files:

name, addr,  data, rw, scale, dis,  unit, tags
ping, 40001, u2,   r,  ,      Ping, ,
do0,  00017, bit,  rw, ,      DO-0, ,
do1,  00017, bit,  rw, ,      DO-1, ,
ai0,  40001, u2,   r,  ,      AI-0, ,
ai1,  40002, u2,   r,  *10,   AI-1, kW,   power

Addressing

Register address are defined with addr column and specified using Modbus convention:

0xxxx  Coil              00001-065536
1xxxx  Discrete Input    10001-165536
3xxxx  Input Register    30001-365536
4xxxx  Holding Register  40001-465536

Ping

A valid ping register is required in order to test connectivity to slave.

Data Type

The data column specifies how register data is modeled.

bit  Bool
u1   Unsigned  8-bit Int
u2   Unsigned 16-bit Int
u4   Unsigned 32-bit Int
s1   Signed  8-bit Int
s2   Signed 16-bit Int
s4   Signed 32-bit Int
s8   Signed 64-bit Int
f4   32-bit Float
f8   64-bit Float

Bit Mask

The bit data type supports a position notation for cases where bits are packed into input or holding registers:

name, addr,  data,  rw
do0,  40101, bit:0, rw
do1,  40101, bit:1, rw
do2,  40101, bit:2, rw

Word and Byte Order

If register data is not stored in network byte order, you can specify the order using a suffix:

u2le   Unsigned 16-bit Int  Little endian byte and word order
u2leb  Unsigned 16-bit Int  Little endian byte order only
u2lew  Unsigned 16-bit Int  Little endian word order only

Read/Write

Read and write permissions are configured using rw column:

rw  Register may be read and written
r   Register is read-only
w   Register is write-only

Scale Factor

An optional scale factor can be applied to registers using the scale column. The scale format is [op] [num] where the factor is a numeric constant.

add:    +1.5
minus:  -0.25
mult:   *10
div:    /1000

Dis, Unit, Tags

The dis, unit, and tags column allow optional pre-configuration for the point during the learn process:

name, addr,  data, rw, dis,  unit, tags
ai1,  40002, u2,   r,  AI-1, kW,   power foo bar

Current Points

Modbus proxy points are configured with modbusCur tag, which maps to a valid register map name:

point
modbusConnRef: @conn
modbusCur: ai0

Writable Points

Modbus proxy points are configured to write to remote system points via the modbusWrite tag:

point
writable
modbusConnRef: @conn
modbusWrite: ao5

History

History synchronization is not supported by Modbus. You will need to use collection to store history.

Block Reads

Modbus connectors will attempt to optimize consecutive registers into a single block read when possible. This behavior can be tuned by adding the modbusBlockGap and modbusBlockMax tags to your modbusConn rec, or by configuring them on the connector's associated conn tuning rec.

modbusBlockGap

By default, blocks require all points to be in truly consecutive registers:

// block 1
40001 u2
40002 u2
40003 u2

// block 2
40005 u2

If you have a small gap in an otherwise sequential run of registers, you can tune to maintain a single read by adding the modbusBlockGap tag to your conn rec. This tag specifies the maximum number of registers that can be skipped for a single block:

modbusConn
modbusBlockGap: 1

// block 1
40001 u2
40002 u2
40003 u2
40005 u2  // 400004 will be read but discarded

modbusBlockMax

By default, blocks are limited to 100 total registers (which includes skipped registers from modbusBlockGap). To force a connector to split blocks into smaller or larger chunks, add the modbusBlockMax tag to your conn rec:

modbusConn
modbusBlockMax: 2

// block 1
40001 u2
40002 u2

// block 2
40003 u2
40004 u2

Be aware a block read failure will result in the entire block's points being marked as fault.

---

---

def

func:modbusLearn

modbusLearn(conn, arg: null)

Deprecated - use connLearn()

---

meta

admin	✓
def	func:modbusLearn
deprecated	✓
is	func
lib	lib:modbus
name	modbusLearn

---

supertypes

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

---

---

def

func:modbusPing

modbusPing(conn)

Deprecated - use connPing()

---

meta

admin	✓
def	func:modbusPing
deprecated	✓
is	func
lib	lib:modbus
name	modbusPing

---

supertypes

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

---

---

def

func:modbusRead

modbusRead(conn, regs)

Read a point value for given register name on connector instance. The regs argument may be a single Str name, or a Str[] for a block read. The grid returned will contain a row for each register requested and two columns: name and val.

---

meta

admin	✓
def	func:modbusRead
is	func
lib	lib:modbus
name	modbusRead

---

supertypes

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

---

---

def

func:modbusRegMap

modbusRegMap(name)

Return given register map contents. Do not include the file extension in the name.

modbusRegMap("myRegisterMap")

---

meta

def	func:modbusRegMap
is	func
lib	lib:modbus
name	modbusRegMap

---

supertypes

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

---

---

def

func:modbusRegMaps

modbusRegMaps()

List installed register maps including source.

---

meta

def	func:modbusRegMaps
is	func
lib	lib:modbus
name	modbusRegMaps

---

supertypes

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

---

---

def

func:modbusSyncCur

modbusSyncCur(points)

Deprecated - use connSyncCur()

---

meta

admin	✓
def	func:modbusSyncCur
deprecated	✓
is	func
lib	lib:modbus
name	modbusSyncCur

---

supertypes

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

---

---

def

func:modbusWrite

modbusWrite(conn, reg, val)

Write a value to given register name on connecter instance.

---

meta

admin	✓
def	func:modbusWrite
is	func
lib	lib:modbus
name	modbusWrite

---

supertypes

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

---

---

def

modbusBlockGap

Applied to modbusConn to allow for gaps in block reads. See modbus for more information.

---

meta

def	modbusBlockGap
is	int
lib	lib:modbus
tagOn	modbusConn

---

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

---

---

def

modbusBlockMax

Applied to modbusConn to limit the maximum number of registers to read in a block read. See modbus for more information.

---

meta

def	modbusBlockMax
is	int
lib	lib:modbus
tagOn	modbusConn

---

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

---

---

def

modbusConn

Modbus connector

---

meta

connFeatures
def	modbusConn
icon	modbus
is	conn
lib	lib:modbus

---

usage

modbusConn  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
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
modbusBlockGap	Applied to modbusConn to allow for gaps in block reads
modbusBlockMax	Applied to modbusConn to limit the maximum number of registers to read in a block read
modbusReadTimeout	How long to wait before timing out on a modbus read
modbusRegMapUri	Applied to modbusConn to define the register map CSV file
modbusSlave	Applied to modbusConn to identify the slave address on this modbus network
modbusWriteTimeout	How long to wait before timing out on a modbus write
uri	Universal resource identifier

---

---

def

modbusConnRef

Used on a proxy point to reference its parent modbusConn

---

meta

def	modbusConnRef
is	ref
lib	lib:modbus
of	modbusConn
tagOn	modbusPoint

---

supertypes

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

---

---

def

modbusCur

Modbus address to use for current value subscriptions. See modbus for format.

---

meta

def	modbusCur
is	str
lib	lib:modbus
tagOn	modbusPoint

---

supertypes

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

---

---

def

modbusPoint

Point which synchronizes data via a Haystack connector.

---

meta

def	modbusPoint
is	connPoint
lib	lib:modbus

---

usage

modbusPoint  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

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
modbusConnRef	Used on a proxy point to reference its parent modbusConn
modbusCur	Modbus address to use for current value subscriptions
modbusWrite	Used on a modbus proxy point to store the id of the entity in the remote system used to write writeVal
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

modbusReadTimeout

How long to wait before timing out on a modbus read.

---

meta

def	modbusReadTimeout
is	duration
lib	lib:modbus
tagOn	modbusConn

---

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

modbusRegMapUri

Applied to modbusConn to define the register map CSV file. This URI must be a path relative to the project's home directory or can be a "fan://" URI to a CSV file bundled in a pod.

---

meta

def	modbusRegMapUri
is	uri
lib	lib:modbus
tagOn	modbusConn
uiInput	modbusExt::ModbusRegMapInput

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
uri	Universal resource identifier

---

---

def

modbusSlave

Applied to modbusConn to identify the slave address on this modbus network.

---

meta

def	modbusSlave
is	int
lib	lib:modbus
tagOn	modbusConn

---

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

---

---

def

modbusWrite

Used on a modbus proxy point to store the id of the entity in the remote system used to write writeVal. See modbus for format.

---

meta

def	modbusWrite
is	str
lib	lib:modbus
tagOn	modbusPoint

---

supertypes

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

---

---

def

modbusWriteTimeout

How long to wait before timing out on a modbus write.

---

meta

def	modbusWriteTimeout
is	duration
lib	lib:modbus
tagOn	modbusConn

---

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:modbusRegMap

Manage Modbus register map files

---

meta

admin	✓
appName	conn
def	view:modbusRegMap
disKey	ui::regMap
icon	view
is	view
lib	lib:modbus

---

supertypes

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

---

src

view: { uiType:"modbusExt::RegMapView" }
data: { expr:"modbusRegMapList()" }