FOCAS Adapter Installation Guide

The MaestroHub FOCAS Adapter is a standalone side-car service that bridges MaestroHub to a FANUC CNC. It links FANUC's fwlib32 library, reaches the control on TCP 8193, and exposes a JSON-over-WebSocket endpoint that the FANUC FOCAS connector consumes. Run one adapter reachable on the plant network; each MaestroHub connection targets one CNC through it.

┌──────────────────┐   WebSocket    ┌──────────────────────────┐    FOCAS     ┌──────────────┐
│ MaestroHub       │◄──────────────►│ FOCAS Adapter            │◄────────────►│ FANUC CNC    │
│ fanuc connector  │  JSON / ws://  │ .NET 8 + fwlib32.dll     │  TCP 8193    │ 0i / 16i /   │
│                  │  :45282/ws     │ (Windows service/exe)    │              │ 30i …        │
└──────────────────┘                └──────────────────────────┘              └──────────────┘

Platform support

The adapter 1.0.0 ships for Windows only (win-x86 and win-x64). Linux and Docker builds are planned for a later release. Run the adapter on a Windows host that can reach the CNC on TCP 8193.

1. Download the adapter

Download the adapter from the MaestroHub portal:

https://portal.maestrohub.com/downloads/plugins

Each release ships a self-contained, single-file archive per build — no .NET runtime install is required on the target host:

Archive	Use when
maestrohub-focas-adapter-1.0.0-win-x86.zip	Your FANUC fwlib32.dll is 32-bit (the most common case on Windows)
maestrohub-focas-adapter-1.0.0-win-x64.zip	Your fwlib32.dll is 64-bit (newer control families only)

Verify the published SHA-256 against the download, then extract the archive to a folder such as C:\focas-adapter\. Each archive contains the adapter executable, a README.txt, and a focas-adapter.config.sample template.

Which bitness?

The adapter loads fwlib32.dll by P/Invoke, so the adapter build's bitness must match the DLL's bitness — a 32-bit DLL cannot load into a 64-bit process, or vice-versa. If unsure, try win-x86 first: if the DLL is actually 64-bit, the adapter fails at startup with an explicit message telling you to switch builds. It never fails silently.

2. Supply the FOCAS library (customer-supplied)

The adapter depends on FANUC's FOCAS library — fwlib32.dll on Windows. This binary is licensed and shipped by FANUC and is not redistributed with MaestroHub — you supply your own lawfully-purchased copy (the same posture as Kepware and other commercial FOCAS gateways). The adapter probes for it at startup and refuses to start if it is absent or the wrong bitness.

• Obtain the FOCAS2 Library, FANUC part A02B-0207-K737, from your FANUC distributor or machine-tool builder. It arrives as a CD/archive containing the platform binaries and fwlib32.h.
• Place fwlib32.dll in a directory the adapter can read (for example C:\focas\), or alongside the adapter executable.

The adapter searches for the library in this order:

1. FOCAS_LIBRARY_PATH — a directory containing fwlib32.dll, or a direct path to the file.
2. The adapter's own executable directory.

CNC-side FOCAS/Ethernet option

The PC-side library is separate from the FOCAS/Ethernet option on the control — a licensed CNC-side option that must be enabled on the machine. A machine without it refuses the connection even when the adapter and library are correct. The connection test reports this distinctly as "option missing" so you can tell it apart from network or authentication failures.

3. Requirements checklist

• A Windows host (x86 or x64) on the same network as the target CNC, able to reach it on TCP 8193.
• The FANUC FOCAS library (fwlib32.dll) for a bitness matching your chosen build (see step 2). Not bundled.
• The FOCAS/Ethernet option enabled on the CNC itself.
• Network reachability from MaestroHub to the adapter's WebSocket port (default 45282).
• No .NET install — the self-contained build bundles the runtime.

4. Configure the adapter

The adapter is configured two interchangeable ways, both using the same FOCAS_* names:

• Config file — focas-adapter.config (KEY=VALUE, # for comments) placed next to the executable is auto-loaded, so a double-click works. Point elsewhere with the FOCAS_CONFIG_FILE environment variable. Start from the shipped focas-adapter.config.sample.
• Environment variables — FOCAS_API_TOKEN=…, etc.

Precedence (highest first): environment variable → config file → built-in default. The startup banner logs which source was used.

Variable	Default	Required	Meaning
FOCAS_API_TOKEN	—	Yes	Auth token. MaestroHub sends it as the raw Authorization header (no Bearer prefix). The adapter refuses to start without it.
FOCAS_LIBRARY_PATH	executable directory	Recommended	Directory (or direct file path) where fwlib32.dll is found.
FOCAS_PORT	45282	No	WebSocket listen port.
FOCAS_LOG_PATH	/var/log/focas-adapter	Recommended on Windows	Adapter log directory. Set a writable Windows path, e.g. C:\ProgramData\MaestroHub\FocasAdapter\logs.
FOCAS_REQUEST_TIMEOUT_MS	10000	No	Per-FOCAS-call watchdog (milliseconds).
FOCAS_MAX_CNC_CONNECTIONS	32	No	Safety cap on concurrent CNC entries.
FOCAS_POS_DECIMALS	3	No	Decimal places applied to raw axis positions (0–9); match your control's least-input increment (3 for metric micron, 4 for inch, …).

Authentication token

The adapter authenticates WebSocket clients with a token presented as the raw Authorization header. Generate a high-entropy random token, set it as FOCAS_API_TOKEN on the adapter, and enter the same value in the connection's API Token field in MaestroHub. Rotate it as you would any shared secret.

Example config file

Copy the sample and fill in the required values:

copy focas-adapter.config.sample focas-adapter.config

# focas-adapter.config
FOCAS_API_TOKEN=<a-long-random-token>
FOCAS_LIBRARY_PATH=C:\focas
FOCAS_LOG_PATH=C:\ProgramData\MaestroHub\FocasAdapter\logs
FOCAS_PORT=45282
FOCAS_POS_DECIMALS=3

5. Run the adapter

Interactively (quick start / testing)

With focas-adapter.config in the same folder as the executable, just start it (a double-click works too):

.\maestrohub-focas-adapter.exe

Or drive it entirely from environment variables:

$env:FOCAS_API_TOKEN    = "your-token"
$env:FOCAS_LIBRARY_PATH = "C:\focas"          # directory containing fwlib32.dll
$env:FOCAS_LOG_PATH     = "C:\ProgramData\MaestroHub\FocasAdapter\logs"
.\maestrohub-focas-adapter.exe

The adapter listens on ws://0.0.0.0:45282/ws by default and exposes GET /healthz. The startup banner logs the build, the resolved library path, and the listen address:

MaestroHub FOCAS Adapter 1.0.0 (protocol v1)
Runtime: win-x86 — 32-bit X86 on Microsoft Windows ...
Listening on http://[::]:45282 — WebSocket endpoint /ws, health endpoint /healthz
FOCAS library loaded from C:\focas\fwlib32.dll. ...

Confirm it is up:

curl.exe http://127.0.0.1:45282/healthz
# {"status":"ok","adapterVersion":"1.0.0","protocolVersion":1}

If the adapter refuses to start it fails loud — the reason is printed to stderr and appended to startup-error.log next to the executable (so a vanished console window still leaves a trace). Exit codes follow sysexits.h:

Exit code	Meaning
0	Clean shutdown
69	The FOCAS library is unavailable — not found, not usable, or a bitness mismatch (the message names the build to switch to)
78	Configuration error — e.g. FOCAS_API_TOKEN unset (the message lists what's wrong)

As a Windows service (production)

The adapter distribution provides install-service.ps1 / uninstall-service.ps1 helper scripts. From an elevated PowerShell:

.\install-service.ps1 -BinPath 'C:\focas-adapter\maestrohub-focas-adapter.exe' `
    -ApiToken 'your-token' -LibraryPath 'C:\focas' -Port 45282

This creates the MaestroHubFocasAdapter service (auto-start, auto-restart on failure). It writes focas-adapter.config next to the executable from the parameters you pass (an existing config is preserved unless you add -Force), then starts the service — the service reads that file at startup. Remove it with .\uninstall-service.ps1.

If your download does not include these scripts, register the executable as a service manually — place a focas-adapter.config next to the exe (the service reads it from its own directory at startup), then:

New-Service -Name 'MaestroHubFocasAdapter' `
    -BinaryPathName 'C:\focas-adapter\maestrohub-focas-adapter.exe' `
    -DisplayName 'MaestroHub FOCAS Adapter' -StartupType Automatic
Start-Service MaestroHubFocasAdapter

6. Networking

• MaestroHub → adapter: the WebSocket port (FOCAS_PORT, default 45282). Open it between the MaestroHub host and the adapter host.
• Adapter → CNC: TCP 8193 (FOCAS/Ethernet) to each controller.
• Transport is plain ws://. The adapter does not terminate TLS itself; the connector dials ws://<host>:<port>/ws and sends the API token in the Authorization header. This is fine when both endpoints sit on the same trusted plant LAN. If the adapter is reachable outside that segment — across VLANs, over VPN gateways, or across sites — front it with a TLS-terminating reverse proxy (nginx, Caddy, IIS + ARR) and point the MaestroHub connection at the proxy. Without TLS on the untrusted hop, the API token is snoopable on the wire.

7. Connect MaestroHub to the adapter

Once the adapter is running and healthy:

1. In MaestroHub, go to Connections → New Connection → FANUC FOCAS.
2. Set Adapter Host and Adapter Port to the adapter's host and FOCAS_PORT (default 45282).
3. Set CNC IP Address and CNC Port to the target controller (8193 by default).
4. Set API Token to the exact value of FOCAS_API_TOKEN on the adapter.
5. Leave Auto Connect enabled so the connection binds to the CNC as soon as the WebSocket connects.
6. Use the connection's Test action (the ping) to verify the full path — MaestroHub → adapter → CNC.

The test error text distinguishes the failure modes so the cause is unambiguous:

Result	Meaning / fix
Success	MaestroHub reached the adapter, and the adapter is bound to the CNC.
Adapter unreachable	The adapter host/port is wrong or the adapter isn't running / port not open.
AUTH_FAILED (401)	The connection's API Token does not match the adapter's FOCAS_API_TOKEN.
CNC_UNREACHABLE	The adapter is up but can't reach the CNC on cncHost:cncPort — check plant-network routing/firewall to TCP 8193.
FOCAS_OPTION_MISSING	The FOCAS/Ethernet option is not enabled on the control (a CNC-side licensed option).

8. Troubleshooting

Symptom	Cause / fix
Exits 69, "architecture mismatch"	The fwlib32.dll bitness ≠ the build. The message names the build to switch to (win-x86 ↔ win-x64).
Exits 69, "not found"	fwlib32.dll isn't at FOCAS_LIBRARY_PATH. Fix the path or place the DLL.
Exits 69, "not usable"	File present but the loader refused it — corrupt image or a missing dependency DLL.
Exits 78	Configuration invalid (e.g. FOCAS_API_TOKEN unset). The message lists what's wrong.
MaestroHub shows AUTH_FAILED	Connection API Token ≠ adapter FOCAS_API_TOKEN.
MaestroHub shows CNC_UNREACHABLE	Adapter is up but can't reach the CNC — check routing/firewall to TCP 8193.
Axis positions look wrong-scaled	Adjust FOCAS_POS_DECIMALS to match the control; spindle and feed values are unscaled.

Once the connection tests green, continue with the FANUC FOCAS connector guide to build read, write, subscribe, and status functions, and use them in pipelines via the FANUC orchestrate nodes.