- Generated by
1.16.1
|
Mach Modules Documentation
Lua Module API Documentation
|
Go to the source code of this file.
Functions | |
| LaserMeasureModule | StartMeasurement () |
| Start measurement mode. | |
| LaserMeasureModule | StopMeasurement () |
| Leave measurement mode. | |
| LaserMeasureModule | ZeroOutput (opt_controller_index) |
| Zero an output. Set the offset so that the reported value at the current position is 0.0. | |
| LaserMeasureModule | SetOutputValue (new_value) |
| Set the value for the given output. Set the offset so that the reported value at the current position is 0.0. | |
| LaserMeasureModule | GetOutputValue (within_time_ms, timeout) |
| Get the measured value for a named output, with optional freshness and timeout control. | |
| LaserMeasureModule | GetOutputValueSync (timeout_ms) |
| Synchronously get the measured value for a named output, waiting for a new measurement. | |
| LaserMeasureModule | GetAllOutputValues (timeout) |
| Get all the (optionally, offset) values Get all the measured value (with any offset applied) The plugin maintains a "measurement status" register, indicating: | |
| LaserMeasureModule | GetAllOutputValuesSync () |
| Synchronously get all the (optionally, offset) values Get all the measured value (with any offset applied) The plugin maintains a "measurement status" register, indicating: | |
| LaserMeasureModule | SetOutputOffset (new_offset) |
| Set the offset for the given output. This sets the offset (essentially adding that amount to the raw value). | |
| LaserMeasureModule | ClearOutputOffset (opt_controller_index) |
| Clear the offset for an output, all outputs on a controller, or all outputs on all controllers. Set the offset to zero. | |
| LaserMeasureModule | RunOKCommand (descr) |
| Run an operational command with no return data and do standard error checking/reporting. | |
| LaserMeasureModule | LookupOutput () |
| resolve an output with the given name | |
| LaserMeasureModule | CmdArgs (...) |
| construct an operational command with a variable length list of (optional) arguments | |
| LaserMeasureModule | UpdateAllOutputs () |
| Query the plugin for all configured outputs and populate the module-global Outputs table. | |
| LaserMeasureModule | IsLaserMeasurePluginEnabled () |
| Check whether the LaserMeasure plugin is enabled and initialize it if needed. | |
| LaserMeasureModule | IsConnected () |
| Check to see if the plugin is connected to all the controllers. | |
| LaserMeasureModule | IsMeasuring () |
| Check to see if the plugin is in "measurement mode.". | |
| LaserMeasureModule | OperationalCommand () |
| Issue an operational command to the LaserMeasure plugin and return the response. | |
| LaserMeasureModule | CreatePreCannedCommands () |
| Create pre-canned GUI commands for LaserMeasure plugin control. | |
| LaserMeasureModule ClearOutputOffset | ( | opt_controller_index | ) |
Clear the offset for an output, all outputs on a controller, or all outputs on all controllers. Set the offset to zero.
| [in] | output_name | the name of the output whose offset to clear |
| [in] | opt_controller_index | if specified, clear offsets for all outputs on that controller |
Examples:
-- Clear the offsets for all outputs on all controllers
LaserMeasureModule:ClearOutputOffset()
-- Clear the offsets for all outputs on controller #0
LaserMeasureModule:ClearOutputOffset(nil,0)
-- Clear the offset for the outputs named "Diameter"
LaserMeasureModule:ClearOutputOffset("Diameter")
Clear the offset for a named output, all outputs on a controller, or all outputs on all controllers
Sets the offset to zero for the specified scope. The scope is determined by the combination of arguments provided:
| output_name | (string|nil) The name of the output whose offset to clear, or nil to operate by controller |
| opt_controller_index | (number|nil) If specified and output_name is nil, clears all outputs on this controller |
| LaserMeasureModule CmdArgs | ( | ... | ) |
construct an operational command with a variable length list of (optional) arguments
<command>[;<opt_arg1>[,<opt_arg2>[,...]]]
Any arguments that are nil will be ignored.
Construct an operational command string with a variable-length list of optional arguments
Assembles a command string in the format: <command>[;<arg1>[,<arg2>[,...]]] Arguments that are nil are silently ignored. Non-nil arguments are converted to strings via tostring() and joined with commas. If any arguments are present, they are appended to the command name separated by a semicolon.
| command | (string) The base command name (e.g., "Zero", "StartMeasurement") |
| ... | (any) Variable list of optional arguments; nil values are skipped |
| LaserMeasureModule CreatePreCannedCommands | ( | ) |
Create pre-canned GUI commands for LaserMeasure plugin control.
This should only be invoked from within a GUI module. (...but the library module shouldn't be its own GUI module)
This function should only be invoked from within a GUI module. It registers a set of reusable commands for controlling measurement mode and managing output offsets. Commands created include:
| LaserMeasureModule GetAllOutputValues | ( | timeout | ) |
Get all the (optionally, offset) values Get all the measured value (with any offset applied) The plugin maintains a "measurement status" register, indicating:
| [in] | within_time_ms | require the value to have been taken within this many milliseconds (default: 500) If the value is 0, then no timestamp checking will be performed. |
| [in] | timeout | (optional) Wait until timeout (os.time() units) for a valid measurement. |
Examples:
-- Get all measured values
local values = LaserMeasureModule:GetAllOutputValues()
for name,value in pairs(values):
w.LogF(" %s: %s",name,value)
-- do something meaningful with it.
end
Get the measured values for all configured outputs, with freshness validation
Iterates over all outputs in self.Outputs and calls GetOutputValue() for each, passing the same within_time_ms and timeout arguments. If an output returns nil (invalid or stale measurement), its entry in the result table is set to LaserMeasureModule.CONSTANTS.MeasurementError ("INVALID") rather than nil, since nil cannot be stored as a table value.
| within_time_ms | (number|nil) Require measurements to have been taken within this many milliseconds. Defaults to 500. Pass 0 to disable freshness checking |
| timeout | (number|nil) Wait until this os.time() value for valid measurements. If nil, returns immediately if value is stale |
| LaserMeasureModule GetAllOutputValuesSync | ( | ) |
Synchronously get all the (optionally, offset) values Get all the measured value (with any offset applied) The plugin maintains a "measurement status" register, indicating:
| [in] | timeout_ms | (optional) Wait timeout (milliseconds) for a valid measurement. |
Examples:
-- Get all measured values
local values = LaserMeasureModule:GetAllOutputValuesSync(10.0)
for name,value in pairs(values):
w.LogF(" %s: %s",name,value)
-- do something meaningful with it.
end
Synchronously get all output values, waiting for a fresh measurement from each output
Iterates over all outputs in self.Outputs and calls GetOutputValueSync() for each, distributing the remaining timeout budget across outputs as each one completes. If an output returns nil (invalid or error status), its entry in the result table is set to LaserMeasureModule.CONSTANTS.MeasurementError ("INVALID") rather than nil, since nil cannot be stored as a table value. The total timeout budget shrinks as time passes, so later outputs receive less time than earlier ones.
| timeout_ms | (number|nil) Maximum total time in milliseconds to wait for all measurements. If nil, waits indefinitely |
| LaserMeasureModule GetOutputValue | ( | within_time_ms | , |
| timeout | ) |
Get the measured value for a named output, with optional freshness and timeout control.
Retrieves the current measured value (with any active offset applied) from the output's value register, then validates the measurement using the status register. The status must be "OK" and include a timestamp. If within_time_ms is greater than 0, the timestamp is compared to the current time (using os.time() integer seconds) and the value is rejected if it is too old. If a timeout is also specified, the function loops until a sufficiently fresh value is available or the timeout is exceeded (raising an error via w.Error()). If within_time_ms is 0, no freshness checking is performed.
| output_name | (string) The name of the output to retrieve the value for |
| within_time_ms | (number|nil) Require the measurement to have been taken within this many milliseconds. Defaults to 500. Pass 0 to disable |
| timeout | (number|nil) Wait until this os.time() value for a sufficiently fresh measurement. If nil, returns immediately on stale value (raising an error) |
| LaserMeasureModule GetOutputValueSync | ( | timeout_ms | ) |
Synchronously get the measured value for a named output, waiting for a new measurement.
Unlike GetOutputValue(), this function waits until a measurement with a timestamp newer than the one observed at entry is available, ensuring the returned value is genuinely new rather than a cached result. The status register is checked first; if the status is not "OK", nil is returned immediately regardless of timeout. The comparison uses string ordering on ISO 8601 timestamps. If timeout_ms is provided, raises an error via w.Error() if the deadline is exceeded.
| output_name | (string) The name of the output to retrieve a fresh measurement for |
| timeout_ms | (number|nil) Maximum time in milliseconds to wait for a new measurement. If nil, waits indefinitely |
| LaserMeasureModule IsConnected | ( | ) |
Check to see if the plugin is connected to all the controllers.
Examples:
if not LaserMeasureModule:IsConnected() then
w.Log('Laser controllers are not all connected. Wait and retry.')
return
end
-- proceed
Check whether the LaserMeasure plugin is connected to all controllers
Reads the IsConnected I/O point from the LaserMeasure device to determine if the plugin is connected to all its configured controllers. If the plugin is not enabled or the I/O read fails, returns false. Checking the I/O is the most reliable way to know if the plugin believes it is connected.
| LaserMeasureModule IsLaserMeasurePluginEnabled | ( | ) |
Check whether the LaserMeasure plugin is enabled and initialize it if needed.
If this module is used as a library, it needs to be intelligent about whether the prerequisite module exists (and is enabled).
Attempts to resolve the cmd_Operational register for the LaserMeasure device. The resolved register handle is cached in self._reg.cmd_Operation.hReg after the first successful call, so subsequent calls return immediately. If the register is found for the first time, UpdateAllOutputs() is called to initialize the full output list. If the register is not found (MERROR_REG_NOT_FOUND), returns false. Any unexpected error code raises a Lua error via w.Error().
| LaserMeasureModule IsMeasuring | ( | ) |
Check to see if the plugin is in "measurement mode.".
Examples:
if not LaserMeasureModule:IsMeasuring() then
w.Log('LaserMeasure plugin is not in measurement mode.')
return
end
Check whether the LaserMeasure plugin is currently in measurement mode
Reads the IsMeasuring I/O point from the LaserMeasure device to determine if the plugin is actively measuring. If the plugin is not enabled or the I/O read fails, returns false. Checking the I/O is the most reliable way to know if the plugin believes it is measuring.
| LaserMeasureModule LookupOutput | ( | ) |
resolve an output with the given name
If no output matches, an error is generated.
Resolve a named output to its controller index and output index
Looks up the given output name in the module-global self.Outputs table (populated by UpdateAllOutputs()). If the output is found, returns the ControllerIndex and OutputIndex stored in its info table. If the output name is nil or not found, raises an error via w.Error() — the error is the caller's responsibility to handle.
| output_name | (string) The globally unique name of the output to look up |
| LaserMeasureModule OperationalCommand | ( | ) |
Issue an operational command to the LaserMeasure plugin and return the response.
Issue an operational command to the LaserModule and return the response.
Sends a command string to the plugin via the cmd_Operational register using mc.mcRegSendCommand(). Logs both successful responses and errors via w.LogF(). If the plugin is not enabled, the function returns immediately without sending the command. The command register handle is resolved by calling IsLaserMeasurePluginEnabled() internally.
| op_cmd | (string) The operational command string to send to the plugin (e.g., "GetControllerCount", "Zero;0,1") |
| LaserMeasureModule RunOKCommand | ( | descr | ) |
Run an operational command with no return data and do standard error checking/reporting.
Run an operational command and perform standard error checking and reporting
Sends the given command string to the plugin via OperationalCommand() and checks whether the response is "OK". If the response is not "OK", logs an error message using w.LogF() including the description and the actual response string.
| command | (string) The fully assembled operational command string to send (e.g., from CmdArgs()) |
| descr | (string) A human-readable description of the operation, used in error log messages |
| LaserMeasureModule SetOutputOffset | ( | new_offset | ) |
Set the offset for the given output. This sets the offset (essentially adding that amount to the raw value).
| [in] | output_name | the name of the output to set |
| [in] | new_offset | the new offset to use |
Examples:
-- Set the offset for an output named "Diameter" to -1
LaserMeasureModule:SetOutputOffset("Diameter",-1)
Set the offset for the given named output
Applies the specified offset value to the named output by issuing a "SetOutputOffset" operational command with the resolved controller and output indices. The offset is added to the raw measured value when reporting the output value. LookupOutput() is used internally to resolve the output name to its indices.
| output_name | (string) The name of the output to set the offset for |
| new_offset | (number) The new offset value to apply to the raw measurement |
| LaserMeasureModule SetOutputValue | ( | new_value | ) |
Set the value for the given output. Set the offset so that the reported value at the current position is 0.0.
| [in] | output_name | the name of the output to set |
| [in] | new_value | the target value |
Examples:
-- Set an output named "Diameter" to 3.5
LaserMeasureModule:SetOutputValue("Diameter",3.5)
Set the measured value for a named output by adjusting its offset
Sets the offset such that the value reported at the current position equals new_value. Internally issues a "SetOutputOffsetValue" operational command with the resolved controller index, output index, and desired value. LookupOutput() is used to resolve the output name to its indices.
| output_name | (string) The name of the output to set the value for |
| new_value | (number) The desired reported value at the current position |
| LaserMeasureModule StartMeasurement | ( | ) |
Start measurement mode.
| [in] | opt_controller_index | if specified, only stop measurement on that controller |
Examples:
-- Stop measuring for all outputs on all controllers LaserMeasureModule:StopMeasurement() -- Stop measuring for all outputs on controller #0 LaserMeasureModule:StopMeasurement(0)
Enter measurement mode for all controllers or a specific controller
Sends a "StartMeasurement" operational command to the LaserMeasure plugin. If opt_controller_index is specified, only that controller enters measurement mode; otherwise all controllers start measuring. If the plugin is not enabled, returns immediately.
| opt_controller_index | (number|nil) If specified, start measurement only on this controller. If nil, starts all controllers |
| LaserMeasureModule StopMeasurement | ( | ) |
Leave measurement mode.
| [in] | opt_controller_index | if specified, only stop measurement on that controller |
Examples:
-- Stop measuring for all outputs on all controllers LaserMeasureModule:StopMeasurement() -- Stop measuring for all outputs on controller #0 LaserMeasureModule:StopMeasurement(0)
Leave measurement mode for all controllers or a specific controller
Sends a "StopMeasurement" operational command to the LaserMeasure plugin. If opt_controller_index is specified, only that controller exits measurement mode; otherwise all controllers stop measuring. If the plugin is not enabled, returns immediately.
| opt_controller_index | (number|nil) If specified, stop measurement only on this controller. If nil, stops all controllers |
| LaserMeasureModule UpdateAllOutputs | ( | ) |
Query the plugin for all configured outputs and populate the module-global Outputs table.
Query the plugin for all the outputs. All the interface APIs will use an output name to uniquely identify it. This function should be called at startup (after the LaserMeasure plugin has all its outputs defined) and any time the outputs may have changed (e.g. config end).
NOTE: There's currently no way to re-initialize everything, and there's no explicit check to see if the plugin is finished configuring. Right now (2021-01-21), the plugin attempts to configure synchronously in the CTOR, so by the time the screen loads, all the outputs should be defined.
Iterates over all controllers and all outputs on each controller by issuing operational commands: "GetControllerCount", "GetControllerOutputCount;<idx>", and "GetControllerOutputName;<ctrl>,<out>". For each discovered output, an entry is added to self.Outputs keyed by output name, containing ControllerIndex, OutputIndex, OutputName, and pre-cached register handles for the value, status, and offset registers. Errors at any level are logged via w.LogF() but do not abort the overall iteration.
This function should be called at startup after the LaserMeasure plugin has finished configuring, and again any time the output list may have changed (e.g., after a config reload).
| LaserMeasureModule ZeroOutput | ( | opt_controller_index | ) |
Zero an output. Set the offset so that the reported value at the current position is 0.0.
| [in] | output_name | the name of the output to zero |
| [in] | opt_controller_index | if specified, zero all outputs on that controller |
Examples:
-- zero all outputs on all controllers
LaserMeasureModule:ZeroOutput()
-- zero all outputs on controller #0
LaserMeasureModule:ZeroOutput(nil,0)
-- zero an outputs named "Diameter"
LaserMeasureModule:ZeroOutput("Diameter")
Zero a named output, all outputs on a controller, or all outputs on all controllers
Sets the offset so that the reported value at the current position is 0.0. The scope of the operation is determined by the combination of arguments:
| output_name | (string|nil) The name of the output to zero, or nil to operate by controller scope |
| opt_controller_index | (number|nil) If specified and output_name is nil, zeros all outputs on this controller |
1.16.1