FANUC FOCAS Integration Guide

Connect MaestroHub to FANUC CNC controllers (0i, 16i/18i/21i, 30i/31i/32i families) through a FOCAS adapter gateway. The adapter runs on a plant-network machine, links FANUC's fwlib32 library, and reaches the CNC on TCP 8193; MaestroHub talks to the adapter over JSON-over-WebSocket. One MaestroHub connection targets one CNC.

Overview

The FANUC FOCAS connector provides:

• WebSocket-based communication with a FOCAS adapter side-car that bridges to the CNC via FANUC's fwlib32 library
• Curated address catalog browsing — a controller-specialized tree of the data points available on the connected CNC (there is no discoverable namespace on a CNC, so this catalog is the onboarding template)
• Batch reads of status, axis positions, spindle, feed, macros, PMC, and alarms, with per-item error isolation
• Writes to macro variables and PMC memory, with per-item success/error results
• Change-pushed subscriptions via adapter-side polling with configurable interval and deadband — the trigger for event-driven flows
• One-call machine status snapshot — an MTConnect-shaped object for dashboards

Prerequisites

The MaestroHub FOCAS Adapter must be installed and running on a machine that has network access to the target FANUC CNC. The adapter provides the WebSocket endpoint and handles all fwlib32 communication with the control. It requires FANUC's FOCAS library binaries, which are supplied by the customer (FANUC licenses these; see the installation guide).

Download the adapter from https://portal.maestrohub.com/downloads/plugins. Version 1.0.0 runs on Windows only (win-x86 / win-x64); it is a self-contained build that needs no separate .NET install.

For step-by-step instructions on downloading, licensing, configuring, and running the adapter, see the FOCAS Adapter Installation Guide.

Quick Start

An end-to-end setup, from adapter to a running pipeline:

1. Install the adapter. Download it from the portal, supply the FOCAS fwlib32.dll, set FOCAS_API_TOKEN, and run it on a Windows host that can reach the CNC. See the Installation Guide.
2. Create the connection. In MaestroHub go to Connections → New Connection → FANUC FOCAS, point it at the adapter host/port and the CNC IP, and enter the same API token. Run the connection Test to confirm MaestroHub → adapter → CNC.
3. Build functions. Add a Read, Write, Subscribe, or Status function. Use the Browse Catalog panel in the Read/Subscribe/Write forms to pick addresses without memorizing the syntax.
4. Use them in a pipeline. Drop the function onto a pipeline as a FANUC orchestrate node, or start a pipeline from a FANUC trigger when values change.

Connection Configuration

Creating a FANUC FOCAS Connection

Navigate to Connections → New Connection → FANUC FOCAS and configure the following fields.

1. Profile Information

Field	Type	Required	Default	Description
Connection Name	Text	Yes	-	A unique, descriptive name for this connection (1-100 characters)
Description	Text	No	-	Optional description for this connection

2. Adapter & CNC Configuration

Field	Type	Required	Default	Validation	Description
Adapter Host	Text	Yes	-	Non-empty string	Hostname or IP of the machine running the FOCAS adapter
Adapter Port	Number	No	45282	1 - 65535	Adapter WebSocket port
CNC IP Address	Text	Yes	-	Non-empty string	IP address of the target FANUC CNC on the plant network
CNC Port	Number	No	8193	1 - 65535	FOCAS/Ethernet port on the CNC (default 8193)
CNC Series	Select	No	auto	one of the listed values	Controller-family dialect. auto detects it via cnc_sysinfo on connect. Options: auto, 30i, 0i-df, 16-18-21-0iabc, 15i
Auto Connect	Toggle	No	true	-	Automatically bind to the CNC when the WebSocket connects

Adapter URL format

The full WebSocket URL is constructed automatically: ws://{host}:{port}/ws Example: ws://192.168.1.50:45282/ws

3. Authentication

Field	Type	Required	Default	Description
API Token	Password	Yes	-	Adapter authentication token, sent as the raw Authorization header (stored securely, encrypted at rest)

4. Advanced

Field	Type	Default	Range	Description
Connection Timeout (seconds)	Number	30	1 - 300	Timeout for establishing the adapter/CNC connection
Ping Interval (seconds)	Number	30	5 - 300	Keep-alive ping cadence
Request Timeout (seconds)	Number	30	1 - 3600	Per-request response timeout
Default Poll Interval (ms)	Number	1000	100 - 60000	Default subscription poll interval; the adapter clamps below 100 ms
Default Deadband	Number	0	0 - 1000000	Default absolute numeric delta suppressing tiny changes on subscriptions
Max Subscriptions	Number	1000	1 - 100000	Upper bound on concurrent subscriptions for this connection

Function Builder

Functions define reusable operations against the CNC. Each function has a type that determines its behavior and parameters.

Available Function Types

Function Type	Role	Trigger-capable	Description
Read	On-demand	No	Batch-read one or more FOCAS addresses
Write	On-demand	No	Write macro variables and PMC memory (supports ((templates)))
Subscribe	Trigger	Yes	Register a polled group; the adapter pushes an event on change
Status	On-demand	No	One-call MTConnect-shaped machine snapshot

Browse Catalog (address picker)

The Read, Subscribe, and Write forms include a Browse Catalog panel that helps you discover addresses without memorizing the syntax. It walks the adapter's curated FOCAS catalog as a lazy tree, specialized to the connected controller — axis folders reflect its real axis count (a 3-axis machine shows axis.1 through axis.3). Expanding a folder loads only that level, so a large controller never floods the form.

Nodes come in three kinds:

• Folders (status, axis, pmc, …) — expand to load their children on demand.
• Items — concrete addresses (e.g. axis.1.pos.abs) with an access badge and value type; click Add to append to the address list. In the Write form, read-only items are shown but not addable (they aren't valid write targets).
• Hints — the non-enumerable families (macro.<n>, pmc.<area>.<addr>[.<type>]) appear as a syntax hint with a small input, so you type a concrete address (e.g. macro.500) and add it.

Browse is an internal helper — it is not a standalone function type and has no pipeline node.

Read Addresses

Read batch-reads one or more addresses. Per-item error isolation means one bad address returns an error for that item only — it never fails the batch or drops the connection.

Parameter	Required	Description
Addresses	Yes	List of FOCAS addresses, e.g. axis.1.pos.abs, spindle.1.speed, macro.500

Example output (data): a values array, one entry per requested address, each with a value (and ts) or an error:

{
  "values": [
    { "address": "status.run", "value": "EXECUTING", "ts": "2026-07-09T10:00:00Z" },
    { "address": "axis.1.pos.abs", "value": 123.456, "ts": "2026-07-09T10:00:00Z" },
    { "address": "spindle.1.speed", "value": 2000, "ts": "2026-07-09T10:00:00Z" },
    { "address": "axis.9.pos.abs", "error": { "code": "INVALID_ADDRESS", "message": "no such axis" } }
  ]
}

Write Addresses

Write writes values to writable addresses — macro variables and PMC memory in V1. Writes execute sequentially in request order with per-item success/error results; writes to read-only addresses are rejected per item without affecting the others. Values support ((paramName)) templates that resolve from pipeline input at execution time.

Parameter	Required	Description
Writes	Yes	List of { address, value } items. value may be a literal or a ((template))

Example:

[
  { "address": "macro.500", "value": 42.5 },
  { "address": "pmc.R.10.bit2", "value": true }
]

Example output (data): a per-item results array plus success/failure counts:

{
  "results": [
    { "address": "macro.500", "success": true },
    { "address": "pmc.R.10.bit2", "success": true }
  ],
  "successCount": 2,
  "failureCount": 0
}

A write to a read-only address returns "success": false with an error: { code, message } for that item only, without affecting the others.

Subscribe to Changes

Subscribe registers a polled group of addresses; the adapter polls the CNC and pushes a pipeline event whenever a value changes. This is the standard trigger for event-driven FANUC flows. Each subscription has its own poll interval and optional deadband for numeric items. Subscribe is trigger-only — it starts a pipeline and is not run on demand.

Parameter	Required	Default	Description
Addresses	Yes	-	FOCAS addresses to subscribe to
Poll Interval (ms)	No	1000	Adapter-side poll interval (clamped to a 100 ms floor)
Deadband	No	0	Absolute numeric delta suppressing tiny changes (numeric items only)

Each pushed event carries a payload.values array of { address, value, ts } entries — the payloads are timestamped, so downstream nodes see every change without de-duplication. The first poll cycle sends every subscribed item (initial snapshot); after that, only changed items are pushed.

{
  "payload": {
    "values": [
      { "address": "status.run", "value": "EXECUTING", "ts": "2026-07-09T10:00:01Z" }
    ]
  }
}

See the FANUC Trigger node for the full pipeline event shape and how to reference it downstream.

Machine Status

Status fetches a single MTConnect-shaped machine snapshot — run state, mode, motion, e-stop, alarm flag, spindle and feed actuals, and controller identity — in one call, so a dashboard gets a ready status object instead of composing a dozen reads. It takes no parameters.

Example output (data):

{
  "connected": true,
  "cncHost": "192.168.1.50",
  "cnc": { "series": "30i", "version": "G05.1", "cncType": "M", "axisCount": 3, "spindleCount": 1, "maxAxis": 32, "path": 1 },
  "snapshot": {
    "run": "EXECUTING", "mode": "MEM", "motion": true, "estop": false, "alarm": false,
    "spindle": { "speed": 2500 }, "feed": { "actual": 1200 }
  },
  "stats": { "pollOverruns": 0, "focasCalls": 42, "avgCallMs": 12.4, "queueDepth": 0 }
}

Mid-reconnect the adapter returns "connected": false with the stats block but no live snapshot.

Address Catalog

Addresses use a dotted syntax. <n> denotes a 1-based index (axis, spindle, macro number, PMC address). The catalog below is the V1 published surface; the Browse Catalog picker in the Read/Subscribe/Write forms exposes it as a tree with live axis counts filled in.

Address pattern	Access	Description
status.run · status.mode · status.motion · status.estop · status.alarm	read	Machine status block
sysinfo	read	Series, version, type (M/T), axis count
axis.<n>.pos.abs · .mach · .rel · .dtg	read	Per-axis positions (absolute, machine, relative, distance-to-go)
axis.<n>.load	read	Per-axis servo load %
spindle.<n>.speed · spindle.<n>.load	read	Spindle speed and load
feed.actual · override.feed · override.spindle · override.rapid	read	Feed actual and override percentages
program.number · program.name · program.block · program.sequence	read	Active program info
alarm.active	read	List of active alarms: { type, number, axis, text }
opmsg	read	Operator messages
macro.<n>	read / write	Macro variable, e.g. macro.500
param.<n>[.axis]	read	CNC parameter (write in V1.1)
diag.<n>[.axis]	read	Diagnostics
pmc.<area>.<addr>[.<type>]	read / write	PMC memory, e.g. pmc.D.100.word, pmc.G.8.bit3
tool.offset.<n>.<kind>	read	Tool offset, geometry/wear × length/radius (write in V1.1)

PMC areas: G F X Y A R T K C D E PMC types: bit<n>, byte, word, dword, float

V1 scope

V1 supports all reads above, writes for macro.* and pmc.*, the browse catalog, subscribe, status, and the connection ping (with FOCAS-option diagnosis). Deferred to V1.1: writes for parameters and tool/work offsets, stateful alarm set/clear events, and extended program info. Out of scope: program upload/download, HSSB, unsolicited CNC push, and FANUC robots.

Error Handling

Read and write results isolate errors per item: a single bad address returns a structured error for that item while the rest of the batch succeeds. Permanent errors (invalid address, read-only address, write rejected, unsupported on this model, unsupported command, authentication failed) are reported as non-retryable; transient errors (connection, timeout) are retryable.

A common first-connection failure is the FOCAS/Ethernet option missing on the control — this is a licensed CNC-side option separate from the PC-side FOCAS library. The connection ping distinguishes adapter-unreachable, auth-failed, CNC-unreachable, and option-missing so the cause is clear.

Scaling

The FANUC FOCAS connector uses exclusive, fixed scaling: one client owns the adapter/CNC session for a connection. FOCAS calls on a handle are strictly sequential, so a single owner serializes access to the control.