pyfocas

This project is a barebones reimplementation of the FANUC FOCAS protocol for communicating with a CNC machine.

It only uses UNIX sockets and sends the proper messages / packets instead of relying on vendor libraries.

Sources / Based On

This project relies on the reverse engineering of the FANUC FOCAS protocol by diohpix. The relevant library is pyfanuc.

This reimplementation of the protocol is currently the only way of reliably using FOCAS on a 64bit ARM (aarch64) system as no library for that architecture exists.

Protocol

The protocol is a big endian request-response protocol via UNIX sockets. A full message (either request or response) will be called packet. A packet has headers and at least one subpacket, which in turn consist of multiple blocks detailing the purpose of the packet.

Header

The header looks similar for request and response. A typical header contains the following blocks, with a block being a part of the header or subpacket:

Sync Prefix marks the start of a packet and is always A0 A0 A0 A0.

Packet Origin marks if the packet is a request to the FOCAS server (00 01) or a response from it (different from 00 01).

Packet Type differentiates the packets between:

• Trying to open a connection to the FOCAS server:
  • Request: 01 01
  • Response: 01 02
• Trying to close the connection:
  • Request: 02 01
  • Response: 02 02
• Trying to execute a generic command:
  • Request: 21 01
  • Response: 21 02

There are other packet types as can be seen in diohpix/pyfanuc which are not covered in this project (yet).

Packet Length contains the total length of bytes coming after it, including the size of the Subpacket Count (2 bytes) and all the subpackets in bytes.

Note that this results in the Packet Length always being larger than the sum of all subpacket's Subpacket Length by exactly 2 bytes (size of the Subpacket Count).

Subpacket Count holds the number of subpackets in this packet.

Subpacket

Subpackets are of varying length and data types. There are some reused sizes and packing / types.

Default Payload: 5x 4-Byte INT32

The subpackets are always of length 1c / 28 bytes. They each contain three pieces of information about the subpacket totalling 8 bytes followed by a payload of 20 bytes which can be split into multiple regions.

Implemented Functions

Initialize Connection

This needs to be done to create the connection with the FOCAS server.

Request

Response

The response contains 360 Bytes of (as of yet) unclear subpacket content.

Status Info

Request

With the single subpacket being:

Response

With the single subpacket being:

System Info

Request

With the single subpacket being:

Response

With the single subpacket being:

Read Macro

Request

With the single subpacket being:

This reads macro variable #502 (01 F6).

Response

With the single subpacket being:

Write Macro (Double)

Writes a macro variable with a double value (not scaled integer)

Request

With the single subpacket being:

This writes 100.0 to #502.

Development

Release

In the steps below we assume that you

• installed uv and just, and
• execute commands in the root of the repository.

Please replace <VERSION> with the version number of the package that you want to release (e.g. 0.2.0).

PyPI

To release a new version on PyPI please use the commands below:

just release <VERSION>

GitHub

Open the release notes for the latest version and create a new release:

1. Paste the release notes into the main text of the release web page
2. Insert the version number into the tag field
3. For the release title use “Version ”, where <VERSION> specifies the version number (e.g. “Version 0.2”)
4. Click on “Publish Release”

Note: Alternatively you can also use the gh command:

gh release create

to create the release.