Skip to main content

Keyence Vision VS-Series Smart Camera

Introduction

Overview

The Keyence Vision integration lets a Mach-controlled CNC router use a Keyence VS-series smart camera (such as the VS-L320MX) to locate the center of a printed fiducial mark and report the X/Y offset from the camera center to the mark center.

Typical workflow: the machine jogs or moves under G-code so the camera is positioned within roughly two inches of the printed mark, then an M280 call triggers the camera to measure and stores the offset values in OEM parameter registers where the operator screen and downstream G-code can read them.

Communication uses the Keyence Non-Procedural command interface over TCP/IP. The control sends TRG on the data output port and the camera replies with the configured Data Output (Non-Procedural) tool values.

Components

File Purpose
Modules/Addons/KeyenceVisionModule.lua TCP non-procedural client. Opens the socket, sends TRG, parses the response, and writes results to OEM parameters.
Modules/CommonMCodeModule.lua (_m280) M-code implementation that calls KeyenceVisionModule.ReadOffset().
Profiles/Mill/Macros/m280.mcs G-code macro wrapper that invokes _m280.

Camera Setup

Network Configuration

  • Default camera IP expected by Mach: 192.168.208.80 — configurable via OEM parameter KeyenceVisionIP. The camera must be set to this address (or the OEM parameter must be changed to match the camera).
  • TCP port for command + data output: 8500 (default) — configurable via KeyenceVisionPort.
  • Socket I/O timeout: 3 seconds (default) — configurable via KeyenceVisionTimeout.
  • End delimiter: CR (0x0D) (camera default; the module assumes this).

VS Creator Job Requirements

The job loaded on the camera must be configured to emit the mark-center offset in response to a TRG command:

  1. The camera must be in Run Mode. Data Output (Non-Procedural) only fires in Run Mode.
  2. Configure the trigger source as Communication / Command so TRG initiates a measurement.
  3. Add a Data Output (Non-Procedural) tool that emits comma-separated values in one of the following formats:
    • dx,dy — the X and Y offset from the camera center to the mark center.
    • judgment,dx,dy — judgment (1 = OK, 0 = NG) followed by the offsets.
  4. Confirm the end delimiter is CR.

The offset values are returned in whatever units the camera job is configured to output. Make sure the camera units match the units expected by the program reading the OEM parameters.

OEM Parameters

Configuration Parameters

Name Type Default Description
KeyenceVisionEnabled number 0 0 = disabled (module not loaded, M280 is a no-op). 1 = enabled.
KeyenceVisionIP string 192.168.208.80 IP address of the camera.
KeyenceVisionPort number 8500 TCP port for the non-procedural interface.
KeyenceVisionTimeout number 3 Socket I/O timeout in seconds.

Result Parameters

After every M280 call, the module writes the camera result to the following OEM parameters. G-code, scripts, and screen DROs can read them at any time.

Name Type Description
KeyenceVisionLastJudgment number -1 = unknown / not reported by the camera. 0 = NG (fail). 1 = OK (pass).
KeyenceVisionLastOffsetX number X offset from camera center to mark center, in camera units. Signed.
KeyenceVisionLastOffsetY number Y offset from camera center to mark center, in camera units. Signed.
KeyenceVisionLastStatus string "OK" on success, otherwise a human-readable error message (e.g. "timeout", "connection refused", "ER,TRG,07").

Module Loading

The module is loaded automatically by both the screen environment and the M-code environment whenever KeyenceVisionEnabled equals 1. Loading happens in:

  • CommonGUIModule.LoadAllModules() — exposed as global kv for screen scripts.
  • ModuleLoader.RequireCommonMCodeModulesAndGlobals() — exposed as global kv for M-code scripts.

When KeyenceVisionEnabled is 0, the module is not loaded and no TCP code runs. M280 still exists but logs a message and returns success without contacting the camera.

M280 — Trigger Camera Read

Overview

Triggers a single measurement on the camera and stores the result in the KeyenceVisionLast* OEM parameters. The G-code program is responsible for first positioning the camera over the mark.

Parameters

Letter Description
P Error-handling mode (optional).
0 or omitted = soft-fail: log error, continue program.
Non-zero = halt: stop the program on camera error or NG judgment.

Examples

(Position camera over mark)
G0 X10.0 Y8.0
M280                 (read offset, soft-fail on camera error)
(Halt the program if the camera fails or returns NG)
G0 X10.0 Y8.0
M280 P1

Behavior

  1. If KeyenceVisionEnabled is 0, the call is logged and returns success immediately.
  2. Opens a TCP socket to KeyenceVisionIP:KeyenceVisionPort with timeout KeyenceVisionTimeout.
  3. Sends TRG\r.
  4. Reads response lines, skipping the TRG echo and any empty lines, up to 8 lines total.
  5. Parses the first data line as either dx,dy (judgment defaults to -1) or judgment,dx,dy.
  6. Writes KeyenceVisionLastJudgment, KeyenceVisionLastOffsetX, KeyenceVisionLastOffsetY, and KeyenceVisionLastStatus.
  7. If P is non-zero and the camera errored or returned NG (judgment = 0), halts the program with w.Error().

If the configured Data Output emits only dx,dy (no judgment field), KeyenceVisionLastJudgment is set to -1. In that case M280 P1 will halt only on transport errors (timeout, refused, malformed response), not on a missing judgment field.

Reading the Result from G-code

After M280 completes, the operator screen and any G-code or macro script can read the result from the OEM parameters listed above. From a G-code subroutine or another macro, the values can be retrieved with the standard wrapper helpers:

local dx     = w.GetOEMParamValue("KeyenceVisionLastOffsetX")
local dy     = w.GetOEMParamValue("KeyenceVisionLastOffsetY")
local judge  = w.GetOEMParamValue("KeyenceVisionLastJudgment")
local status = w.GetOEMParamValueString("KeyenceVisionLastStatus")

Reading into Pound Variables with M242

M242 is the general MachMotion macro for reading an OEM parameter and writing the value into a pound variable. Use it after M280 to expose the Keyence result to standard G-code math.

Parameters:

  • V — the pound variable that will receive the value read from the OEM parameter.
  • (Data:"<ParamName>") — a G-code comment on the same line that names the OEM parameter to read.

Example — trigger the camera, then load each result into a pound variable:

G0 X10.0 Y8.0
M280                                          (read offset)
M242 V550 (Data:"KeyenceVisionLastOffsetX")   (#550 = X offset)
M242 V551 (Data:"KeyenceVisionLastOffsetY")   (#551 = Y offset)
M242 V552 (Data:"KeyenceVisionLastJudgment")  (#552 = judgment)

(Now #550 and #551 can be used in G-code math, e.g. apply correction)
G10 L2 P1 X[#550] Y[#551]

M242 reads numeric OEM parameters. KeyenceVisionLastStatus is a string and should be read with w.GetOEMParamValueString() from a Lua script rather than with M242.

Error Handling and Diagnostics

Error Types

Symptom Likely Cause
timeout Camera unreachable, wrong IP/port, or no data tool configured to emit on TRG.
connection refused Camera not in Run Mode, or another client already holds the socket.
ER,TRG,01 Unknown command — the camera does not accept TRG in its current mode.
ER,TRG,06 Command not executable — the camera is not in Run Mode or the trigger source is not set to Communication.
ER,TRG,07 Camera-side timeout — measurement did not complete within the camera's configured window.
Malformed response The Data Output (Non-Procedural) tool is missing, disabled, or configured to emit something other than the expected fields.

Status Storage

On every call (success or fail), KeyenceVisionLastStatus is updated. On failure it contains the error text returned from the parse or socket layer; on success it contains "OK". Operators can surface this on the screen as a diagnostic DRO.

The camera reports an offset relative to its own center, not to the spindle or tool. Any mechanical offset between the camera and the working tool must be accounted for separately (for example, by applying a head-shift or fixture-offset adjustment in G-code after reading KeyenceVisionLastOffsetX / KeyenceVisionLastOffsetY).

Protocol Reference

The module implements a minimal subset of the Keyence VS Non-Procedural protocol. See the Keyence VS series user manual for the full command set.

Command Description
TRG Trigger a single measurement. Camera echoes TRG\r and then emits the configured Data Output (Non-Procedural) line(s).
FVR Firmware version read. Used by KeyenceVisionModule.TestConnection() as a connectivity check.
  • Each command is terminated with CR (0x0D).
  • Maximum command size: 500 bytes.
  • Camera-side per-command timeout: 3 seconds.
  • Error responses follow ER,<cmd>,<nn>\r, where nn is a two-digit error code (01 unknown, 02 args, 03 range, 04 type, 05 not acceptable, 06 not executable, 07 timeout).
Back to top