3.5 Edit the Script
1. Launch a text or code editor to create a new JavaScript file.
2. Review the script one function at a time. There are four functions that must be implemented in
the script to support solicited ethernet communications.
• onProfileLoad: Retrieves driver metadata
• onValidateTag: Verifies the address and data type created in the configuration or any
dynamic tags created in an OPC client are valid for the end device connected
• onTagsRequest: Builds a packet of bytes to transmit to the device across the wire.
• onData: Interprets the response from the device and updates tag values or indicates if the
read or write operation was successful based on the data in the response.
Note: onTagsRequest and onData can do much more then described in this example. These
functions can be used to communicate with many kinds of protocols. For more information
view the Profile Library Plugin Help documentation.
3. Build out the script one function at a time, use the following information to edit the script.
Required function: onProfileLoad
The onProfileLoad function is the first of these functions called by the driver. It retrieves driver
metadata, identifying the interface between the script and the driver by specifying the version of
Universal Device Driver with which it was created as well as the mode. For more information on
the mode please view the Profile Library plug-in help.
Note: The only supported version is 2.0. Any other value is rejected, leading to failure of all
subsequent functions. Any exception thrown out of any of the “framework” functions is
caught and results in failure of the current operation. An exception thrown out of:
• onProfileLoad causes all subsequent operations to fail until corrected
• onValidateTag causes the tag address to be treated as “invalid”
• onTagsRequest causes the read or write operation on the current tag to fail
• onData causes the read or write operation on the current tag to fail
Below is the entire onProfileLoad function:
function onProfileLoad() {
return { version: “2.0”, mode: “Client” };
}
Required function: onValidateTag
The onValidateTag script function is to validate the address syntax of a tag and the data type,
which is central to communicating with a device. In the case of a Modbus device, this function
ensures that an address is a holding register in the supported range.
If desired, add logic to this function to modify various tag fields, such as providing a valid default
data type,r modifying an address format to enforce consistency among tag addresses, or
assigning a bulkId to group specific tags together.
For the onValidateTag function in this Modbus example, review the sections:
www.ptc.com 6 ©2021-2023 PTC, Inc. All Rights Reserved.
// Validate the address is a holding register in the supported range
let tagAddress = info.tag.address;
try {
let numericAddress = parseInt(tagAddress, 10);
if (numericAddress < MINREGISTERADDRESS || numericAddress > MAXREGISTERADDRESS ||
isNaN(numericAddress)) {
info.tag.valid = false;
return info.tag;
}
// If grouping tags into bulks, assign bulkId now.
// Otherwise, the next bulkId is assigned by default.
let bulkId = Math.floor((numericAddress - MINREGISTERADDRESS)/BULKREGISTERCOUNT);
info.tag.bulkId = bulkId;
log(`Modbus Ethernet onValidateTag: Bulk register count ${BULKREGISTERCOUNT},
address ${tagAddress}, bulkId ${info.tag.bulkId}`, VERBOSE_LOGGING);
info.tag.valid = true;
return info.tag;
}
catch (e) {
// Use log to provide helpful information that can assist with error resolution
log(`Unexpected error (onValidateTag): ${e.message}`, VERBOSE_LOGGING);
info.tag.valid = false;
return info.tag;
}
The code above offers a look at the JavaScript object info that the driver provides to the script
writer. This object is meant to hold data to be exchanged between the script and the driver.
It checks the address received from the driver (info.tag.address) and verifies it is in the
expected range for a Modbus holding register as defined by constants MINREGISTERADDRESS,
MAXREGISTERADDRESS. If it’s not in that range, fail the tag being added by setting the valid field
of the tag to false: info.tag.valid = false.
The script also defines the bulkId field for each tag. The register in the address along with the
BULKREGISTERCOUNT constant facilitates assigning the bulkId that allows blocking together
consecutive registers. Once the tags are blocked together, the Universal Device driver will then
provide them in the tags object passed to the onTagsRequest and onData functions.
// Provide a valid default data type based on register
// Note: "Default" is an invalid data type
let validDataTypes = {"3": "Word", "4": "Word"}
if (info.tag.dataType === "Default") {
let registerChar = info.tag.address.charAt(0);
info.tag.dataType = validDataTypes[registerChar];
}
/*
www.ptc.com 7 ©2021-2023 PTC, Inc. All Rights Reserved.
* The regular expression to compare address to.
* ^4 starts with '4'
* 0* find zero or more occurrences of '0'
* 1$ ends with '1'
*/
let addressRegex = /^40*1$/;
// Correct a "semi-correct" tag address (e.g. 401 or 400001 --> 40001) with regex
if (addressRegex.test(info.tag.address)) {
info.tag.address = "40001";
}
The above code provides examples of logic to modify various tag fields. The first code block
resets the data type if Default is initially selected. While Default is a Kepware server data type, it
is an invalid return value for a tag data type (i.e., info.tag.dataType). As such, provide an
appropriate and valid data type based on the register if the data type is set as Default.
The second code block uses a regex to recognize semi-correct addresses and modify them
accordingly. In the above implementation, this logic adjusts tag addresses with too few or too
many zeros; for example, ‘401’ or ‘400001` is changed to ‘40001’.
Below is the entire onValidateTag function:
function onValidateTag(info) {
// Provide a valid default data type based on register
// Note: "Default" is an invalid data type
let validDataTypes = {"3": "Long", "4": "DWord"}
if (info.tag.dataType === "Default") {
let registerChar = info.tag.address.charAt(0);
info.tag.dataType = validDataTypes[registerChar];
}
/*
* The regular expression to compare address to.
* ^4 starts with '4'
* 0* find zero or more occurrences of '0'
* 1$ ends with '1'
*/
let addressRegex = /^40*1$/;
// Correct a "semi-correct" tag address (e.g. 401 or 400001 --> 40001) with regex
if (addressRegex.test(info.tag.address)) {
info.tag.address = "40001";
}
// Validate the address is a holding register in the supported range
let tagAddress = info.tag.address;
try {
www.ptc.com 8 ©2021-2023 PTC, Inc. All Rights Reserved.
let numericAddress = parseInt(tagAddress, 10);
if (numericAddress < MINREGISTERADDRESS || numericAddress > MAXREGISTERADDRESS ||
isNaN(numericAddress)) {
info.tag.valid = false;
return info.tag;
}
// If grouping tags into bulks, assign bulkId now.
// Otherwise, the next bulkId is assigned by default.
let bulkId = Math.floor((numericAddress - MINREGISTERADDRESS)/BULKREGISTERCOUNT);
info.tag.bulkId = bulkId;
log(`Modbus Ethernet onValidateTag: Bulk register count ${BULKREGISTERCOUNT},
address ${tagAddress}, bulkId ${info.tag.bulkId}`, VERBOSE_LOGGING);
info.tag.valid = true;
return info.tag;
}
catch (e) {
// Use log to provide helpful information that can assist with error resolution
log(`Unexpected error (onValidateTag): ${e.message}`, VERBOSE_LOGGING);
info.tag.valid = false;
return info.tag;
}
}
Required function: onTagsRequest
The onTagsRequest script function builds a packet of bytes that is sent to the target Modbus
device. In the example implementation, the onTagsRequest function makes use of two helper
functions to build action-specific packet: BuildReadMessage and BuildWriteMessage:
function onTagsRequest(info) {
let action = "Fail";
if (info.type === "Read") {
let readData = BuildReadMessage(info.tags);
// Evaluate if the data was successfully built
if (readData.length === 12) {
action = "Receive";
}
return { action: action, data: readData };
} else if (info.type === "Write") {
SENTWRITEDATA = BuildWriteMessage(info.tags);
// Evaluate if the data was successfully built
www.ptc.com 9 ©2021-2023 PTC, Inc. All Rights Reserved.
if (SENTWRITEDATA.length === 12) {
action = "Receive";
}
return { action: action, data: SENTWRITEDATA };
}
}
Unlike the onTagsRequest function, these helper functions are not required; they help make the
script more manageable. Let’s dive into these helper functions now.
Helper Function: BuildReadMessage
This function builds into the packet the function code for a Modbus read to ensure that the read
is on the appropriate address(es). Most of the Modbus-specific pieces of this snippet are
documented in code comments with the important parts called out.
The Modbus protocol supports blocking / bulk read and write functionality. The Universal Device
Driver supports blocking tags for reads but does not support blocking tags for writes. The tags
parameter is an array containing at least one tag element. If, in onValidateTag, the script
assigned the same bulkId to more than one tag, then those tags sharing a bulkId are included in
the array when the request type is Read.
function BuildReadMessage (tags) {
// This should never happen, but it's best practice
if (tags.length === 0) {
throw "No tags were requested for read request.";
}
// Sort the Modbus registers low to high
let registers = [];
for(let i=0; i<tags.length; i++) { registers[i] = parseInt(tags[i].address, 10); }
registers.sort (sortNumber);
// Find the lowest register, and the number of registers required to read the whole block
let first = registers[0];
let count = registers[registers.length - 1] - first + 1;
// Get the zero-based register index to make the request
first -= 40001;
The code above checks the tags component of the JavaScript object info (i.e. info.tags). This
component holds an array of tags. Each tag has an address used to build a request packet for a
read. The beginning of this section of code ensures that the driver has given a tag to build a
request packet. If the length of the tags array is zero, it exits the function because there's no
reason for the driver to build a request packet if no tag – and in turn, no address – is provided.
www.ptc.com 10 ©2021-2023 PTC, Inc. All Rights Reserved.
// Update the transaction ID in the stateful transaction object
if (TXID === undefined) {
TXID = 0;
} else {
TXID++;
}
JavaScript is not a strongly typed language, making it possible to modify a variable's type or
composition at runtime. This is something to take advantage of within the BuildReadMessage
function. The above code snippet updates the value of a global variable TXID, which represents
a transaction ID exchanged between the script and the driver. Use this global variable to keep
track of the number of times it is building packets to transmit to the device. It's important to
keep track of this because the transaction ID is a necessary part of the Modbus protocol, as
seen in the next step. TXID is stateful between transactions because it is shared between the
script and driver and maintains state across transactions. Every time this function is called, the
transaction ID value maintains the state it was the last time it was changed at runtime.
// Build the Modbus Ethernet data
let data =
// ----Transaction ID------|-Protocol--|---Length--|Server|-Fxn-|
[hiByte(TXID), loByte(TXID), 0x00, 0x00, 0x00, 0x06, 0x00, 0x03,
------Starting Address-------|-------Register count--------|
hiByte(first), loByte(first), hiByte(count), loByte(count)]
The above shows the packet being constructed. It is an array of bytes to be sent to the Modbus
device. The code comments the different parts of the packet that are defined in the Modbus
protocol; for instance, the TXID described earlier is used in the protocol as the top two bytes.
Note: Only bytes are currently supported for the data array.
Below is the entire BuildReadMessage function:
function BuildReadMessage (tags) {
// This should never happen, but it's best practice
if (tags.length === 0) {
throw "No tags were requested for read request.";
}
// Sort the Modbus registers low to high
let registers = [];
for(let i=0; i<tags.length; i++) { registers[i] = parseInt(tags[i].address, 10); }
registers.sort (sortNumber);
// Find the lowest register, and the number of registers required to read the whole block
let first = registers[0];
let count = registers[registers.length - 1] - first + 1;
// Get the zero-based register index to make the request
first -= 40001;
www.ptc.com 11 ©2021-2023 PTC, Inc. All Rights Reserved.
// Initialize or update the transaction ID in the stateful transaction object
if (TXID === undefined) {
TXID = 0;
} else {
TXID++;
}
// Build the Modbus Ethernet data
let data =
// ----Transaction ID------|-Protocol--|---Length--|Server|-Fxn-|------Starting Address---
-
[hiByte(TXID), loByte(TXID), 0x00, 0x00, 0x00, 0x06, 0x00, 0x03, hiByte(first),
---|-------Register count--------|
loByte(first), hiByte(count), loByte(count)]
return data;
}
Helper Function: BuildWriteMessage
The BuildWriteMessage function is similar to the BuildReadMessage function in that it assists
with building an array of bytes to send the device. However, this function facilitates writing a
value to, rather than reading a value from, a Modbus device.
Note: Not all devices support writes. If the target device does support writes, the
BuildWriteMessage function – in conjunction with the ParseWriteMessage function –
provides an example of how to implement this functionality.
// This should never happen but it's best practice
if (tags.length === 0) {
throw "No tags were requested for write request.";
}
// Sort the Modbus registers low to high
let register = parseInt(tags[0].address, 10);
register -= 40001;
// Get the value to write which is located in the first
// element in the tags[n].value object
let value = parseInt(tags[0].value);
The code above assigns the integer value of the tag address to the variable register.
Additionally, is assigns the value of the first tag value to the variable value since KEPServerEX
only allows single writes.
// Build the Modbus Ethernet data
let data =
// ----Transaction ID-----|-Protocol--|---Length--|Server|-Fxn-|
www.ptc.com 12 ©2021-2023 PTC, Inc. All Rights Reserved.
[
hiByte(TXID), loByte(TXID), 0x00, 0x00, 0x00, 0x06, 0x00, 0x06,
--------Starting Address----------|-------value to write--------|
hiByte(register), loByte(register), hiByte(value), loByte(value)
];
return data;
The above shows how to build up a write packet, which is very similar to building a read packet
within the BuildReadMessage function.
Required function: onData
The onData script function parses the array of bytes received from a Modbus device. In the
example implementation, as was the case with the onTagsRequest function, the onData
function uses two helper functions to parse responses from a Modbus device:
ParseReadMessage and ParseWriteMessage:
function onData(info) {
let action = ACTIONFAILURE;
if (info.type === "Read") {
let tags = ParseReadMessage(info.tags, info.data);
// Evaluate if the data was successfully parsed from the packet
if (tags[0].value != null || tags[0].quality != null) {
action = ACTIONCOMPLETE;
}
return { action: action, tags: tags };
} else if (info.type === "Write") {
action = ParseWriteMessage(info.data);
return { action: action, tags: info.tags };
}
}
Helper Function: ParseReadMessage
This function's purpose is to parse an incoming packet into a tag value to update the respective
tag in the server. The incoming packet is passed to the script via the JavaScript object
information as the returned byte array is contained in its data component (i.e. info.data). The
function determines what information is important based on the protocol specification and
extracts the value for the tag/address. This value is assigned to the value field of the tag (e.g.
info.tags[0].value) and then returned from the function, which is how the tag is updated in
the server.
www.ptc.com 13 ©2021-2023 PTC, Inc. All Rights Reserved.
function ParseReadMessage(tags, data) {
// This should never happen but it's best practice
if (tags.length === 0) {
throw "No tags were requested for read request.";
}
log(`Modbus Ethernet ParseReadMessage: data ${JSON.stringify(data)}`,
VERBOSE_LOGGING);
// Convert the string addresses to integers (eg 40001)
let registers = [];
for(let i=0; i < tags.length; i++) { registers[i] = parseInt(tags[i].address, 10); }
// Find the lowest numbered register - this is the starting address
let startingAddress = Array.min (registers);
// MBE Response values start here:
let offset = 9;
// Enough bytes?
if (data.length < offset + 2 * registers.length) {
// Iterate the registers and set the quality of each tag to bad
for (let i = 0; i < registers.length; ++i) {
// Log message only once for this response
if (i === 0) {
if (data.length === offset){
log(`Modbus Ethernet ParseReadMessage: Device returned an error code
${data[7]}, ${data[8]}`);
} else {
log(`Modbus Ethernet ParseReadMessage: Invalid response from device`);
}
}
tags[i].quality = "Bad";
}
}
The code above performs error checking and gathering some information about the
transaction. If the number of bytes in the response is not the number of bytes expected, then
the script sets the quality of each tag to Bad. If the response appears to include an error code
from the device, then the script provides that information in the message passed to the log
function. Otherwise, the script logs a message indicating an invalid response from the device.
The result is an updated tags component of the JavaScript object info to be shared with the
driver and ultimately used to update the tag qualities in the server.
// Iterate the registers and lookup the response value for each
for (let i = 0; i < registers.length; ++i) {
// Calculate the index of this register's value in the response buffer
let index = registers[i] - startingAddress;
// Extract it from the response buffer
www.ptc.com 14 ©2021-2023 PTC, Inc. All Rights Reserved.
let hi = data[2*index + offset];
let lo = data[2*index + offset + 1];
tags[i].value = (wordFromBytes (hi, lo));
}
return tags;
The code above extracts the value returned from the device and assigns it to the appropriate
tag to be used to update the tag value in the server. The result is an updated tags component of
the JavaScript object info to be shared with the driver and ultimately used to update the tag
values in the server.
Below is the entire ParseReadMessage function.
function ParseReadMessage(tags, data) {
// This should never happen but it's best practice
if (tags.length === 0) {
throw "No tags were requested for read request.";
}
log(`Modbus Ethernet ParseReadMessage: data ${JSON.stringify(data)}`,
VERBOSE_LOGGING);
// Convert the string addresses to integers (eg 40001)
let registers = [];
for(let i=0; i < tags.length; i++) { registers[i] = parseInt(tags[i].address, 10); }
// Find the lowest numbered register - this is the starting address
let startingAddress = Array.min (registers);
// MBE Response values start here:
let offset = 9;
// Enough bytes?
if (data.length < offset + 2 * registers.length) {
// Iterate the registers and set the quality of each tag to bad
for (let i = 0; i < registers.length; ++i) {
// Log message only once for this response
if (i === 0) {
if (data.length === offset){
log(`Modbus Ethernet ParseReadMessage: Device returned an error code
${data[7]}, ${data[8]}`);
} else {
log(`Modbus Ethernet ParseReadMessage: Invalid response from device`);
}
}
tags[i].quality = "Bad";
}
www.ptc.com 15 ©2021-2023 PTC, Inc. All Rights Reserved.
} else {
// Iterate the registers and lookup the response value for each.
// Assigning the quality of the tag is optional. If undefined, Good is assumed.
for (let i = 0; i < registers.length; ++i) {
// Calc the index of this register's value in the response buffer
let index = registers[i] - startingAddress;
// Extract the value from the response buffer
let hi = data[2*index + offset];
let lo = data[2*index + offset + 1];
tags[i].value = (wordFromBytes (hi, lo));
}
}
return tags;
}
Helper Function: ParseWriteMessage
The purpose of the ParseWriteMessage function is to determine if the write was successful.
Most devices respond that the request was received and executed. In the case of Modbus, the
response echoes the request, which makes it possible to compare the returned message with
the sent message that was saved in the global variable SENTWRITEDATA.
Below is the entire ParseWriteMessage function:
function ParseWriteMessage(data) {
// Modbus echoes a write request so if the data sent
// does not match the data received, then the write fails
SENTWRITEDATA.forEach((e1) => data.forEach((e2) => {
if (e1 !== e2) {
return "Fail";
}
}));
return "Complete";
}
以上分析总结出重点
扫一扫
644
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
