lmxopcua/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.IntegrationTests/Docker/focas-mock/README.md

focas-mock

focas-mock is a Python TCP mock server for testing higher-level FOCAS clients without a real FANUC control.

The project is built from two inputs:

• The 64-bit FANUC-related DLLs downloaded from Ladder99/fanuc-cnc-api
• The vendor fwlib.cs interop file, used as the callable surface reference

The DLLs are not reimplemented at the binary ABI level. Instead, this project extracts their export tables, builds per-version capability profiles, exposes a JSON-over-TCP mock API, and implements the targeted native FOCAS Ethernet wire protocol used by OtOpcUa fixed-tree tests.

What is included

• Vendored 64-bit DLLs under vendor/fanuc-cnc-api/64bit/
• A profile extractor that inspects PE exports with pefile
• A Windows P/Invoke shim source under shim/ for clients that load FWLIB64.dll directly
• Built-in profiles for:
  • FWLIB64
  • fwlib0DN64
  • fwlib0iD64
  • fwlib30i64
  • fwlibe64
  • fwlibNCG64
• A stateful mock server with:
  • version/profile switching
  • forced error injection
  • runtime state patching
  • built-in default mock data
  • auto-detected native FOCAS Ethernet PDU handling for the targeted API subset

Quick start

Install in editable mode:

python -m pip install -e .

List the generated profiles:

focas-mock list-profiles

Start the mock server with the 30i profile:

focas-mock serve --profile fwlib30i64 --host 127.0.0.1 --port 8193

Start with a JSON patch file that overrides the default data:

focas-mock serve --profile fwlib30i64 --data examples/mock-30i.json

Protocol

The server accepts two protocols on the same port:

• newline-delimited JSON for fixture control and shim tests
• native FOCAS Ethernet binary PDUs from the real fwlibe64.dll

JSON requests are one object per line:

{"id":1,"method":"cnc_allclibhndl3","params":{"ipaddr":"127.0.0.1","port":8193,"timeout":10}}

Example response:

{"id":1,"method":"cnc_allclibhndl3","rc":0,"message":"EW_OK","result":{"FlibHndl":1,"profile":"fwlib30i64"}}

Supported admin methods:

• mock_get_state
• mock_patch
• mock_reset
• mock_load_profile
• mock_list_methods
• mock_schedule_alarms

Example patch request:

{"id":2,"method":"mock_patch","params":{"state":{"parameters":{"6711":{"type":"long","value":1234,"decimal":0}}}}}

Native FOCAS Ethernet clients do not use the JSON request format. Seed profile and fixture state with JSON first, then point cnc_allclibhndl3 at the same host and port. Wire-level details are documented in docs/FOCAS_WIRE_PROTOCOL.md.

For clients that should avoid FANUC DLL loading entirely, dotnet/Focas.Wire contains a native C# read-only TCP client for the verified wire subset. It does not expose write APIs; use the JSON control channel to preset fixture state.

Example test setup over TCP:

{"id":1,"method":"mock_load_profile","params":{"profile":"FWLIB64"}}
{"id":2,"method":"mock_patch","params":{"state":{"pmc":{"R":{"100":{"type":"byte","value":1}}},"parameters":{"6711":{"type":"long","value":1234,"decimal":0}},"macros":{"500":{"value":42000,"decimal":3}},"statinfo":{"run":3,"aut":1,"emergency":0},"alarms":[{"alm_no":100,"type":1,"axis":0,"msg":"TEST ALARM"}]}}}
{"id":3,"method":"cnc_allclibhndl3","params":{"ipaddr":"127.0.0.1","port":8193,"timeout":10}}
{"id":4,"method":"pmc_rdpmcrng","params":{"FlibHndl":1,"area":"R","data_type":"byte","start":100,"end":100}}

Regenerating profiles

The built-in JSON profiles are generated from the vendored binaries:

python -m focas_mock.cli extract-profiles

By default this reads:

• vendor/fanuc-cnc-api/64bit/*.dll
• upstream/fwlib.cs

and writes:

• src/focas_mock/builtin_profiles/*.json

Testing Direct P/Invoke Clients

If a client directly P/Invokes FANUC's 64-bit DLLs, point it at the shim DLLs built from shim/ instead of the real vendor DLLs. The shim exports the small FOCAS surface used by the client and forwards calls to this Python server over JSON/TCP.

focas-mock serve --profile FWLIB64 --host 127.0.0.1 --port 8193
.\shim\build.ps1
$env:FOCAS_MOCK_HOST = "127.0.0.1"
$env:FOCAS_MOCK_PORT = "8193"

Before running the client, seed profile/state with mock_load_profile and mock_patch as shown above.

Detailed documentation for the supported FOCAS subset is in docs/USED_FOCAS_API.md. Native Ethernet wire notes are in docs/FOCAS_WIRE_PROTOCOL.md. OtOpcUa-specific setup notes are in docs/OTOPCUA_DOTNET_INTEGRATION.md.

Implemented mock calls

The server currently implements a practical subset of the surface observed in the exported DLLs and the C# wrapper:

• cnc_allclibhndl
• cnc_allclibhndl2
• cnc_allclibhndl3
• cnc_freelibhndl
• cnc_sysinfo
• cnc_statinfo
• cnc_rddynamic2
• cnc_actf
• cnc_acts
• cnc_acts2
• cnc_getpath
• cnc_setpath
• cnc_rdaxisname
• cnc_rdspdlname
• cnc_rdparam
• cnc_wrparam
• cnc_rdmacro
• cnc_wrmacro
• cnc_rdalmmsg2
• pmc_rdpmcrng
• pmc_wrpmcrng
• cnc_rdopmsg
• cnc_rdopmode
• cnc_rdprgnum
• cnc_exeprgname2
• cnc_rdexecprog
• cnc_rdseqnum
• cnc_rdblkcount
• cnc_rdproginfo
• cnc_rdprogdir3
• cnc_rdtimer
• cnc_rdspmeter
• cnc_rdsvmeter
• cnc_rdspload
• cnc_rdspgear
• cnc_rdspmaxrpm
• cnc_rddiagnum
• cnc_rddiaginfo
• cnc_diagnoss

Limitations

• This is not a binary-compatible replacement for FANUC's DLLs.
• Native FOCAS Ethernet support is intentionally scoped to the targeted API subset documented in docs/FOCAS_WIRE_PROTOCOL.md.
• The per-version profiles are grounded in exported symbol tables plus the published interop wrapper, while some defaults such as axis-count hints are inferred from filename families and documented as heuristics.