Introduction
To get started with an overview of V2 Adapter Scripts, visit this Knowledge Base Article.
A variable is a piece of named data that is produced by transforming other data available in an adapter script. Variables are defined in a section called variables. Some examples of problems you might solve with variables are:
- Turning a sensor signal into an execution state
- Counting parts on a pulsing signal
- Combining multiple signals into a single state
Here’s an example of a variable that counts parts based on an analog input that transitions to a high voltage state for a few seconds each time a part is made:
variables:
part-count:
- source: AIN0
- threshold: 5
- rising-edge
- count
Using the example above, the variable is defined by the unique name part-count, and the body of the variable is a list of operations. Each line beginning with a dash is an operation. Operations can be thought of as steps of work performed one after the other. Each step takes the result of the previous step as its input, performs some work on it, and then outputs it for the next step to use. The part-count variable can be described as that series of steps.
- Wait for changes on the AIN0 pin. When a change is noticed, then pass it to...
- A threshold operation, which converts the value to true or false if it is above or below the threshold value. Pass the threshold value to...
- A rising edge detector operation, which watches the value for changes from false to true (low to high). This modifies the input to be true only at the moment the transition occurs, and false at all other times, essentially marking a point in time that an event has occurred. Pass the countable value to...
- A count operation, which increments by one for each “event” that was detected in the previous step. There are no steps to pass the counter value to, so assign it as the result of the variable instead.
The first operation in the list represents a special case because there is no previous operation passing a value to it. The first operation is limited to a small set of operations that are able to watch other data for changes. When changes occur, the chain of operations will be run through. The list of these supported “starter” operations are source, expression, and state.
The last operation is also special, because there is no following operation to pass its result to. Instead, the result becomes the value of the variable itself, which can be referenced in other parts of an adapter script.
See the Expressions document for more information on how variables and other data sources can reference each other and cause cascading updates.
Topics covered in this article
Operation Reference
The operation reference is organized into a number of groups:
Expression Operations
Expression operations work on a variety of input and allow output to be defined using complex mathematical or logical expressions. The source operation is a special type of expression operation that must be used at the start of each variable definition.
Source
Syntax
- source: identifier or expression
Every variable definition starts with a source operation. The source line identifies the data source that will feed the sequence of operations that follows. A valid data source can be a pin, register, or tag name depending on the device being configured. A source can also be another variable name, in which case the final output of the named variable will feed into the start of the new variable’s operation chain.
A source can either be a simple name, or can be a complex expression referencing one or more valid data source identifiers. When any of the data sources referenced are updated, the expression will be evaluated and the result passed on to the next stage.
Examples
- source: AIN0
- source: another-variable
- source: AIN1 + AIN2
Expression
Syntax
- expression: expression
An expression operation applies a mathematical (or in limited cases, non-mathematical) expression to its input. The result of the calculated expression is the output of the operation.
Expression values recognize the special keyword this, which represents to the value input from the previous operation. Other valid identifiers in the adapter script, which could come from sources or other variable definitions, can also be used in expressions.
See the related Expression support document for the full capability of expressions.
Example
- source: AIN0
- expression: this * 9 / 5 + 32
and
Syntax
- and: expression
An and operation is a special form of the general expression operation, where the input value is implicitly combined with the expression result via a logical AND operation. It is equivalent to:
- expression: this and (expression)
Example
- source: AIN0 > 2
- and: AIN1 > 2
or
Syntax
- or: expression
An or operation is a special form of the general expression operation, where the input value is implicitly combined with the expression result via a logical OR operation. It is equivalent to:
- expression: this or (expression)
Example
- source: AIN0 > 2
- or: AIN1 > 2
State
Syntax
Compact syntax:
- state:
- RESULT1: expression 1
- RESULT2: expression 2
- RESULT3: expression 3
Extended syntax:
- state:
- select: Result 1
when: expression 1
- select: Result 2
when: expression 2
- select: Result 3
when: expression 3
A state operation is a control structure that allows a constant value to be assigned to a variable (or emitted to the next operation in the chain) based on testing a series of expressions. State is similar to an if/else statement in other programming languages.
State operations can have any number of result/expression pairs. When any variable or data source within any of the state’s expressions changes, the entire state will be recalculated by evaluating each expression in the order they are provided. If an expression evaluates to true, the associated result will be captured and no further evaluation will occur. If an expression evaluates to false, the next expression in the list will be checked. If all expressions evaluate to false, then the result of the state operation will be the value passed into it from the previous operation in the chain, or UNAVAILABLE if it’s the first operation.
Expressions within the state’s rules can reference any other variable or data source within the adapter script. If the state operation is NOT the first operation, then the special value this is also available for use, and holds the value passed in from the previous operation.
You should normally prefer the compact syntax for this operation. If you are trying to assign values that are more complex and might interfere with the YAML structure, then use the extended syntax instead.
Examples
# Capturing a basic execution value
- state:
- ACTIVE: is-powered and is-cutting
- READY: true
# Overriding an execution value
- source: exec
- state:
- READY: this == "ACTIVE" and in-warmup-program
Sample Operations
resample
- resample: value
- resample:
interval: value
Resamples an analog data stream to a given sample rate, specified in seconds. The outgoing sample rate will be fixed even if the incoming sample rate is variable or inconsistent.
If the sample interval is larger than the source interval, resampling is calculated by taking every Nth sample from the source where N is resample-interval / source-interval. If N is a fraction and a calculated sample falls between two source samples, the older sample will be emitted.
If the resample interval is smaller than the source interval, resampling is calculated by emitting N samples for every source sample, where N is source-interval / resample-interval. The previous received source sample is repeated for each of N samples until a sample’s time matches or crosses the new sample time.
Note: The resample operation has a built-in safety limit. If more than 5 minutes passes between samples being passed to resample, then only the most recent 5 minutes of resampled values will be calculated.
Example
- source: AIN0
- resample: 0.5
Analog Operations
Analog operations primarily consume analog input and produce analog output. The threshold operation is an exception that produces a digital (Boolean) output instead.
threshold
Syntax
- threshold: value
Converts the output of the previous operation into a digital high (true) if its value is above or equal to the threshold value, or a digital low (false) if the value is below.
In addition to the general-purpose expression operations, threshold is the only operation that converts analog inputs into digital outputs.
Example
- source: AIN0
- threshold: 2.5
average
Syntax
- average:
count: sample window size
For each incoming sample, outputs the average of the previous count samples seen.
Example
- source: AIN0
- average:
count: 1
max
Syntax
- max:
count: sample window size
For each incoming sample, outputs the largest of the previous count samples seen.
A max operation can filter out short drops in an input and will delay recognizing decreases in incoming samples. The digital counterpart to max is the off-delay operation.
Example
- source: AIN0
- max:
count: 100
min
Syntax
- min:
count: sample window size
For each incoming sample, outputs the smallest of the previous count samples seen.
A min operation can filter out short rises in an input and will delay recognizing increases in incoming samples. The digital counterpart to min is the on-delay operation.
Example
- source: AIN0
- min:
count: 100
min-delta
Syntax
- min-delta: value
When min-delta gets its first sample, it will remember the value and continue to output that value as new samples come in unless the difference between the sample and the remembered value exceeds the min-delta value. When the difference is exceeded, min-delta will output and remember the new sample.
This operation has the effect of quantizing an input into a smaller set of discrete values, although it is not guaranteed to always pick the same ones. Small min-delta values can be useful for removing minor signal noise and reducing the amount of data that flows out of the operation chain.
Example
- source: AIN0
- min-delta: 1
Digital Operations
Digital operations primarily consume a digital input and produce a digital output. When applied to analog inputs, they typically treat any non-zero values as being true, and zero values being false.
invert
Syntax
- invert
The invert operation does not take any arguments. It inverts the output of the previous operation such that true becomes false, and false becomes true.
If the previous operation produces an analog value, then a value of 0 will become true, and any other value will become false.
Example
- source: AIN0
- threshold: 4
- invert
on-delay
Syntax
- on-delay: window size
Outputs a false value until the input from the previous stage has maintained a true value for the specified period of time (in seconds), at which point the output switches to true. Any drop to false in the input, even momentary, will switch the output back to false and reset the on-delay counter.
Example
- source: AIN0
- threshold: 4
- on-delay: 0.5
off-delay
Syntax
- off-delay: window size
Outputs a true value until the input from the previous stage has maintained a false value for the specified period of time (in seconds), at which point the output switches to false. Any rise to true in the input, even momentary, will switch the output back to true and reset the on-delay counter.
Example
- source: AIN0
- threshold: 4
- off-delay: 0.5
debounce
Syntax
- debounce: window size
The debounce operation filters out brief changes in a digital input that last less the specified window size (in seconds). Debouncing will help lock a signal into its predominant state.
Setting a debounce is similar to setting an on-delay and off-delay simultaneously.
Example
- source: AIN0
- threshold: 4
- debounce: 0.25
Event Operations
Event operations examine an input signal for specific events, such as the transition of a state from low to high, and output a 0-length true state each time an event is found. At all other times, these operations output a false state. Following event operations with an off-delay will give length to the otherwise infinitely short event pulses.
edge
Syntax
- edge
The edge operation does not take any parameters. It watches a digital input and emits an event pulse each time the input transitions from either high to low or low to high.
Example
- source: AIN0
- threshold: 2.5
- edge
falling-edge
Syntax
- falling-edge
The falling-edge operation does not take any parameters. It watches a digital input and emits an event pulse each time the input transitions from high to low.
Example
- source: AIN0
- threshold: 2.5
- falling-edge
rising-edge
Syntax
- rising-edge
The rising-edge operation does not take any parameters. It watches a digital input and emits an event pulse each time the input transitions from low to high.
Example
- source: AIN0
- threshold: 2.5
- rising-edge
value-change
Syntax
- value-change
The value-change operation does not take any parameters. It watches an input for any change in value and emits an event pulse each time a change is seen.
For an unfiltered analog input, an event could be emitted as frequently as every sample.
Example
- source: AIN0
- min-delta: 1
- value-change
value-decrease
Syntax
- value-decrease
The value-decrease operation does not take any parameters. It watches an analog input and emits an event pulse each time the value decreases.
One application of value-decrease is to detect a counter input resetting to a lower value.
Example
- source: AIN0
- min-delta: 1
- value-decrease
value-increase
Syntax
- value-increase
The value-increase operation does not take any parameters. It watches an analog input and emits an event pulse each time the value increases.
One application of value-increase is to detect a counter input incrementing while ignoring a reset to a lower value.
Example
- source: AIN0
- min-delta: 1
- value-increase
Counter Operations
Counter operations are a special group of operations that watch an input and maintain an internal counter in response to certain events. Each time the counter changes, its value is emitted as output. Counter output is considered an analog type and can be further processed by other analog operations in special situations that might call for it.
count
Syntax
- count
The count operation does not take any parameters. Count operations are intended to follow any of the documented event operations, but they can be triggered by any transition from low to high in the input.
Each time count is triggered, its internal value is incremented by 1, and then that value is output. The internal count value is reset to 0 when the adapter restarts.
Example
- source: AIN0
- threshold: 2.5
- falling-edge
- count
window-count
Syntax
- window-count: window size
The window-count operation watches the input for any triggering events, and maintains a count of all the events seen within a preceding window size, specified in seconds.
The internal value of the window-count will fluctuate up and down as events pass into and out of the window being watched. Each time the internal counter changes, the count will be output.
Example
- source: AIN0
- threshold: 2.5
- falling-edge
- window-count: 1
Text Operations
Text (also called String) operations allow inspecting or transforming text data sources, such as a program name. Some basic text support is already provided in the generic Expression operation. For example, it’s possible to test if a variable or data input holding text matches a specific word by using the == operator.
pattern-match
Syntax
- pattern-match: regular expression
- pattern-match:
pattern: regular expression
group: capture group
else: default string
The pattern-match operation allows searching for a pattern within text and capturing the part of text matching the pattern.
The pattern argument is mandatory. Its value can be a simple string, such as a word or a number. The value can also be a full regular expression, allowing for more complicated matches to take place. Regular expressions should always be surrounded in a pair of forward slashes (/). The slashes won’t be considered part of the pattern itself.
The group argument is optional and is only used when the pattern being matched is a regular expression. Regular expressions allow using parentheses to create “capturing groups”, which are smaller patterns within a larger pattern. Capturing groups are assigned a number starting with 1 as they appear within a pattern string. Setting the group argument to the number of a capturing group will cause only that part of the pattern to be captured by the operation. By default, the entire pattern will be captured.
The else argument is optional. If a match can’t be found in the input string, the result of the operation will be the value specified in else instead. If no else value is specified, then the result is an empty string.
Pattern matching is an advanced technical topic. You should have familiarity with common regular expression syntax and rules if you plan to capture patterns more complex than an exact string match.
Examples
- source: program-name
- pattern-match:
pattern: WARMUP1
INPUT: CNCpart1
RESULT:
INPUT: WARMUP1
RESULT: WARMUP1
INPUT: WARMUP2
RESULT:
- source: program-name
- pattern-match:
pattern: /O7[0-9]+/
INPUT: O8003
RESULT:
INPUT: O7005
RESULT: O7005
- source: program-name
- pattern-match:
pattern: /O(7[0-9]+)/
group: 1
else: -1
INPUT: O8003
RESULT: -1
INPUT: O7005
RESULT: 7005
pattern-replace
Syntax
- pattern-replace:
pattern: regular expression
with: replacement
else: default string
The pattern-replace operation allows searching for a pattern within text and replacing the part of text matching the pattern with another value.
The pattern argument is mandatory. Its value can be a simple string, such as a word or a number. The value can also be a full regular expression, allowing for more complicated matches to take place. Regular expressions should always be surrounded in a pair of forward slashes (/). The slashes won’t be considered part of the pattern itself.
The with argument is mandatory. This is the replacement for each instance of a pattern match. The entire matching value can itself be used as part of the replacement by using the symbol $0. If parentheses were used in the pattern (representing parts of the pattern), those matching parts can be used in the replacement by using symbols $1, $2, $3, etc. Numbers are assigned in the order that the parentheses groups appear from left to right.
The else argument is optional. If a match can’t be found in the input string, the result of the operation will be the value specified in else instead. If no else value is specified, then the result is the original unmodified string.
Pattern matching is an advanced technical topic. You should have familiarity with common regular expression syntax and rules if you plan to replace patterns more complex than an exact string match.
Example
- source: program-name
- pattern-replace:
pattern: O7001
with: O7003
INPUT: O8000
RESULT: O8000
INPUT: O7001
RESULT: O7003
- source: program-name
- pattern-replace:
pattern: /O([0-9]+)/
with: $1
INPUT: O9013
RESULT: 9013
INPUT: OX123
RESULT: OX123
- source: program-name
- pattern-replace:
pattern: /O([0-9]+)/
with: $1
else: 0
INPUT: O9013
RESULT: 9013
INPUT: OX123
RESULT: 0
pattern-test
Syntax
- pattern-test: regular expression
The pattern-test operation tests for the existence of a pattern with text. If the pattern exists one or more times, the result of pattern-test is true, otherwise it is false.
The argument to pattern-test can be a simple string, such as a word or a number. The value can also be a full regular expression, allowing for more complicated matches to take place. Regular expressions should always be surrounded in a pair of forward slashes (/). The slashes won’t be considered part of the pattern itself.
Pattern matching is an advanced technical topic. You should have familiarity with common regular expression syntax and rules if you plan to replace patterns more complex than an exact string match.
Example
- source: program-name
- pattern-test: WARMUP
INPUT: WARMUP1
RESULT: true
INPUT: O7003
RESULT: false
- source: program-name
- pattern-test: /O[0-9]+/
INPUT: O7003
RESULT: true
INPUT: 9001
RESULT: false
Misc Operations
Misc operations don’t fit cleanly into other categories or are used internally by MachineMetrics.
log-file
Syntax
- log-file: name
- log-file:
name: name
format: format string
repeat-values: true or false
The log-file operation is an internal operation sometimes used by MachineMetrics to help diagnose problems with an integration by logging data to disk for later review. They are not intended to be written by end-users, but you may still encounter one in an adapter script.
Multiple log-file operations can be used within a variable definition. Any inputs to log-file operations are passed through transparently to the next operation. Each of the log-file operations within a single adapter script must be given a unique name. A shorthand and longhand form are available.
In the longhand syntax, a format string can be provided. Format strings support special placeholders:
- $VALUE - The formatted value of inputs to the logging operation.
- $TIMESTAMP - The decimal Unix timestamp of values being logged.
- $DATETIME - a formatted ISO date and time of values being logged.
The default format string if none is provided is: $TIMESTAMP\t$VALUE
Values are not repeated in logs by default. This behavior can be changed with the repeat-values option.
Logging is limited to 10MB of data or 24 hours of data, whichever is exhausted sooner.
Examples
- source: AIN0
- log-file: sample1.log
- source: AIN0
- log-file:
name: sample2.log
format: $DATETIME - $VALUE
repeat-values: true
Have Questions?
Reach out to support@machinemetrics.com for additional help.
Comments
0 comments
Please sign in to leave a comment.