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:
// 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]; } /*
* 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 {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
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.
// 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.
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";
}
把3.5以上各个代码段，整理成一段完整的代码，这段代码必须有合理性，可直接复制出来能运行的代码。
本文介绍了一种配置参数的方法，特别关注于如何设置回调函数作为配置的一部分。此配置可用于多种编程场景，例如保存方法的定制流程。
扫一扫
661
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
