- Generated by
1.16.1
|
Mach Modules Documentation
Lua Module API Documentation
|
Go to the source code of this file.
Functions | |
| MotionFilterModule | IsMotionFilterPluginEnabled () |
| Check whether the MotionFilter plugin is enabled in the Mach4 profile. | |
| MotionFilterModule | SendCommand (command) |
| Send a command string to the MotionFilter plugin via its API register. | |
| MotionFilterModule | EnableLogging (enable) |
| Enable or disable logging in the MotionFilter plugin. | |
| MotionFilterModule | DisableLogging () |
| Disable logging in the MotionFilter plugin. | |
| MotionFilterModule | LogAxis (axis) |
| Send a log axis command for a specific axis to the MotionFilter plugin. | |
| MotionFilterModule | QuickLog (axis) |
| Send a quick log command for a specific axis to the MotionFilter plugin. | |
| MotionFilterModule | QuickLogAll () |
| Send a quick log command for all axes to the MotionFilter plugin. | |
| MotionFilterModule | VerifyAxisAtZero (axis_id, message) |
| Verify that a specified axis is at the zero position within tolerance. | |
| MotionFilterModule | OverrideAxis (primary_axis_id, secondary_axis_id) |
| create (or replace) an axis override, where commanded motion on <secondary_axis_id> influences motion on <primary_axis_id> | |
| MotionFilterModule | RemoveOverrideAxis (primary_axis_id, secondary_axis_id) |
| remove an axis override, uniquely specified by (<primary_axis_id>,<secondary_axis_id>) | |
| MotionFilterModule | IsAxisOverridden (primary_axis_id, secondary_axis_id) |
| Check whether a specific axis override is currently active. | |
| MotionFilterModule | GearAxis (master, slave, ratio) |
| Gear a slave axis to a master axis with a specified motion ratio. | |
| MotionFilterModule | UngearAxis (master, slave) |
| Remove axis gearing between a slave axis and its master axis. | |
| MotionFilterModule | SetSquaringAngle (angled_axis, following_axis, degrees) |
| Set the squaring compensation angle between an angled axis and a following axis. | |
| MotionFilterModule | LockSquaring (enable, adjust_units) |
| Enable or disable the squaring lock on the MotionFilter plugin. | |
| MotionFilterModule | UnlockSquaring () |
| Disable squaring lock by delegating to LockSquaring with enable=false. | |
| MotionFilterModule test | Run (index) |
| Execute a single MotionFilter test unit by index and record its result. | |
| MotionFilterModule test | RunAll () |
| Execute all registered MotionFilter test units sequentially. | |
| MotionFilterModule test | PrintResults (test_idx, elapsed_time, test_status, response_msg) |
| Safely record test results to CSV, displaying a dialog on internal error. | |
| MotionFilterModule test | EnableMachine () |
| Ensure the machine is enabled and ready for motion, enabling it if necessary. | |
| MotionFilterModule test | axisletter (axis) |
| Convert a Mach4 axis constant to its corresponding G-code letter string. | |
| MotionFilterModule test | CheckBasisMatrix (angle_matrix, solution, inverse, adjust_units) |
| Validate squaring angle and basis matrix calculations against expected solutions. | |
| MotionFilterModule test axisletter | ( | axis | ) |
Convert a Mach4 axis constant to its corresponding G-code letter string.
Maps the standard mc.X_AXIS through mc.C_AXIS constants to their single-character G-code letter equivalents ("X", "Y", "Z", "A", "B", "C"). Raises an error if the axis constant does not correspond to any known axis letter.
| axis | (number) A Mach4 axis constant (e.g., mc.X_AXIS, mc.Y_AXIS, mc.Z_AXIS, mc.A_AXIS, mc.B_AXIS, mc.C_AXIS) |
| MotionFilterModule test CheckBasisMatrix | ( | angle_matrix | , |
| solution | , | ||
| inverse | , | ||
| adjust_units | ) |
Validate squaring angle and basis matrix calculations against expected solutions.
Unlocks squaring, applies a provided angle matrix by calling mf.SetSquaringAngle() for all off-diagonal entries, then locks squaring. Reads the resulting basis and inverse basis matrices from MotionFilter registers, truncates values to 6 decimal places, and compares them element-by-element against the provided solution and inverse tables. Writes the computed matrices to 'basis_matrix.txt' for diagnostic reference. Raises an error if any matrix element does not match the expected value.
| angle_matrix | (table) 2D array (NxN) of squaring angles in degrees. Off-diagonal entry [r][c] specifies the angle between axis (r-1) (angled) and axis (c-1) (follower). Diagonal entries are ignored. |
| solution | (table) 2D array (NxN) of expected basis matrix values, truncated to 6 decimal places |
| inverse | (table) 2D array (NxN) of expected inverse basis matrix values, truncated to 6 decimal places |
| adjust_units | (boolean) If true, passes adjust_units=true to mf.LockSquaring(), scaling the basis matrix to compensate for unit differences between axes |
| MotionFilterModule DisableLogging | ( | ) |
Disable logging in the MotionFilter plugin.
Convenience wrapper that calls MotionFilterModule.EnableLogging(false) to send the "enable logging;0" command to the MotionFilter plugin.
| MotionFilterModule EnableLogging | ( | enable | ) |
Enable or disable logging in the MotionFilter plugin.
Sends an "enable logging" command to the MotionFilter plugin with a sub-parameter of 1 (enable) or 0 (disable). If enable is nil or any value other than false or 0, logging is enabled by default.
| enable | (boolean|number|nil) True or 1 to enable logging, false or 0 to disable. If nil, logging is enabled. |
| MotionFilterModule test EnableMachine | ( | ) |
Ensure the machine is enabled and ready for motion, enabling it if necessary.
Checks whether the machine is currently enabled via the OSIG_MACHINE_ENABLED signal. If it is not enabled, calls w.SetMachEnable(true) and m.StartEnableSequence(0) to enable it. After the enable attempt, re-checks the signal and raises an error if the machine is still not enabled. Intended to be called at the start of motion-based test cases.
| MotionFilterModule GearAxis | ( | master | , |
| slave | , | ||
| ratio | ) |
Gear a slave axis to a master axis with a specified motion ratio.
Sends a "lock axis gearing" command to the MotionFilter plugin, causing the slave axis motor to receive additional motion proportional to the master axis motor movement scaled by the ratio. The slave's planner position is unaffected; only the motor output is modified. The ratio may be negative to invert the slave's direction. If ratio is nil, defaults to 1. Requires the MotionFilter plugin to be enabled.
| master | (number) The master axis index (0-based) whose motion drives the slave |
| slave | (number) The slave axis index (0-based) that receives proportional motion |
| ratio | (number|nil) The gearing ratio applied to the master's motor motion. Negative values invert the slave direction. Defaults to 1 if nil. |
| MotionFilterModule IsAxisOverridden | ( | primary_axis_id | , |
| secondary_axis_id | ) |
Check whether a specific axis override is currently active.
Reads the "MotionFilter/AxisOverrides" register string and parses it into a lookup table of primary:secondary axis pairs. Returns true if the given (primary_axis_id, secondary_axis_id) pair is present in the current overrides. Returns false if the register is empty, nil, or does not contain the specified pair. Requires the MotionFilter plugin to be enabled.
| primary_axis_id | (number) The primary axis index (0-based) to check for an override |
| secondary_axis_id | (number) The secondary axis index (0-based) expected to be paired with the primary axis |
| MotionFilterModule IsMotionFilterPluginEnabled | ( | ) |
Check whether the MotionFilter plugin is enabled in the Mach4 profile.
Reads the "MotionFilter" integer value from the "Plugins" section of the Mach4 profile using w.api("mcProfileGetInt"). Returns true only if the stored value equals 1. This check is used by most MotionFilterModule functions as a guard before sending commands to the plugin.
| MotionFilterModule LockSquaring | ( | enable | , |
| adjust_units | ) |
Enable or disable the squaring lock on the MotionFilter plugin.
Sends a "lock squaring" command to the MotionFilter plugin with two sub-parameters: whether squaring is enabled (1) or disabled (0), and whether to adjust units (1) or not (0). The enable parameter defaults to enabled if nil. The adjust_units parameter defaults to disabled (0) if nil. Requires the MotionFilter plugin to be active.
| enable | (boolean|number|nil) True or 1 to lock squaring, false or 0 to unlock. If nil, squaring is locked (enabled by default). |
| adjust_units | (boolean|number|nil) True or 1 to enable unit adjustment compensation, false, 0, or nil to disable unit adjustment. |
| MotionFilterModule LogAxis | ( | axis | ) |
Send a log axis command for a specific axis to the MotionFilter plugin.
Sends a "log axis" command with the specified axis index via MotionFilterModule.SendCommand(), instructing the plugin to record detailed position data for that axis.
| axis | (number) The axis index (0-based) to log |
| MotionFilterModule OverrideAxis | ( | primary_axis_id | , |
| secondary_axis_id | ) |
create (or replace) an axis override, where commanded motion on <secondary_axis_id> influences motion on <primary_axis_id>
Create or replace an axis override so secondary axis motion influences the primary axis
Verifies that the secondary axis is at zero position, then sends an "override axis" command to the MotionFilter plugin. When active, commanded motion on the secondary axis will be applied as additional motion on the primary axis. Both axes must be at zero before the override is established to prevent position discontinuities.
| primary_axis_id | (number) The primary axis index (0-based) that will receive override motion from the secondary axis |
| secondary_axis_id | (number) The secondary axis index (0-based) whose motion will influence the primary axis; must be at zero position before override is applied |
| MotionFilterModule test PrintResults | ( | test_idx | , |
| elapsed_time | , | ||
| test_status | , | ||
| response_msg | ) |
Safely record test results to CSV, displaying a dialog on internal error.
Wraps MotionFilterModule.test._PrintResults() in a pcall to prevent uncaught errors from propagating. If _PrintResults raises an error, displays a wx message box describing the failure. This function always returns without raising.
| test_idx | (number) The index of the test unit that was executed |
| elapsed_time | (number) Wall-clock time the test took to run, in seconds |
| test_status | (boolean) True if the test passed (pcall returned true), false if it failed |
| response_msg | (string) The return value or error message from the test unit |
| MotionFilterModule QuickLog | ( | axis | ) |
Send a quick log command for a specific axis to the MotionFilter plugin.
Sends a "quick log" command with the specified axis index via MotionFilterModule.SendCommand(), triggering the plugin to capture a brief position snapshot for that axis.
| axis | (number) The axis index (0-based) to quick-log |
| MotionFilterModule QuickLogAll | ( | ) |
Send a quick log command for all axes to the MotionFilter plugin.
Convenience wrapper that sends the "quick log all" command via MotionFilterModule.SendCommand(), triggering the plugin to log position data for every axis.
| MotionFilterModule RemoveOverrideAxis | ( | primary_axis_id | , |
| secondary_axis_id | ) |
remove an axis override, uniquely specified by (<primary_axis_id>,<secondary_axis_id>)
This undoes the effects of OverrideAxis(...)
Remove an existing axis override between a primary and secondary axis
Verifies that the secondary axis is at zero position, then sends a "remove override axis" command to the MotionFilter plugin to eliminate the override relationship previously created by OverrideAxis(). Both axes must be at zero before removal to prevent position discontinuities.
| primary_axis_id | (number) The primary axis index (0-based) that was receiving override influence |
| secondary_axis_id | (number) The secondary axis index (0-based) that was providing override influence; must be at zero position before removal |
| MotionFilterModule test Run | ( | index | ) |
Execute a single MotionFilter test unit by index and record its result.
Looks up the test function at MotionFilterModule.test.units[index], measures its execution time using os.clock(), and runs it inside pcall() to safely capture any errors. Calls MotionFilterModule.test.PrintResults() to write results to the CSV file, and logs a pass or fail message to the operator log via w.OperatorLog().
| index | (number) The 1-based index of the test unit to run within MotionFilterModule.test.units |
| MotionFilterModule test RunAll | ( | ) |
Execute all registered MotionFilter test units sequentially.
Iterates over the MotionFilterModule.test.units array from index 1 to the last entry, calling MotionFilterModule.test.Run() for each. Results are logged and written to the CSV results file by each Run() call. Tests continue even if individual tests fail.
| MotionFilterModule SendCommand | ( | command | ) |
Send a command string to the MotionFilter plugin via its API register.
Obtains (or reuses) a cached handle to the "MotionFilter/API" register, then sends the command string using mc.mcRegSendCommand(). Both the outgoing command and the plugin response are written to the Mach4 controller log via mc.mcCntlLog() for diagnostic purposes. If the API register handle cannot be obtained, the function returns immediately with a MERROR_REG_NOT_FOUND error code and no command is sent. The handle is cached in MotionFilterModule.api_handle across calls to avoid repeated handle lookups.
| command | (string) The command string to send to the MotionFilter plugin API register |
| MotionFilterModule SetSquaringAngle | ( | angled_axis | , |
| following_axis | , | ||
| degrees | ) |
Set the squaring compensation angle between an angled axis and a following axis.
Sends a "set squaring angle" command to the MotionFilter plugin specifying how many degrees the angled axis is off-square, and which following axis will compensate. The degrees value must be between -89 and +89 (exclusive); values at or beyond ±90 are rejected by the plugin. The sign of degrees determines the direction the following axis moves to compensate. If degrees is nil, it defaults to 0 (no squaring correction).
| angled_axis | (number) The axis index that is physically off-square (0-based, must be within mc.MC_MAX_COORD_AXES and must not equal following_axis) |
| following_axis | (number) The axis index that will move to compensate for the angled axis (0-based, must be within mc.MC_MAX_COORD_AXES and must not equal angled_axis) |
| degrees | (number|nil) Angle in degrees that the angled axis is off-square. Must be in the range (-89, +89). If nil, defaults to 0. |
| MotionFilterModule UngearAxis | ( | master | , |
| slave | ) |
Remove axis gearing between a slave axis and its master axis.
Sends an "unlock axis gearing" command to the MotionFilter plugin to decouple the slave axis from the master axis. After ungearing, the slave axis will no longer receive additional motion derived from the master's movement. Requires the MotionFilter plugin to be enabled.
| master | (number) The master axis index (0-based) that was driving the slave |
| slave | (number) The slave axis index (0-based) to decouple from the master |
| MotionFilterModule UnlockSquaring | ( | ) |
Disable squaring lock by delegating to LockSquaring with enable=false.
Convenience wrapper that calls MotionFilterModule.LockSquaring(false) to release the squaring constraint. Requires the MotionFilter plugin to be enabled.
| MotionFilterModule VerifyAxisAtZero | ( | axis_id | , |
| message | ) |
Verify that a specified axis is at the zero position within tolerance.
Retrieves the current position of the given axis using mc.mcAxisGetPos() and checks that its absolute value is within 1E-4 units of zero. If the axis is not sufficiently close to zero, raises a Lua error via w.Error() that includes the provided message, the instance number, the axis index, and the actual position. Also raises an error if the MotionFilter plugin is not enabled.
| axis_id | (number) The axis index (0-based) to verify is at zero position |
| message | (string) A descriptive context message included in the error if the check fails |
1.16.1