If you happen to find this useful, leave a quick note in the Discussions section. If something doesn't work, open an issue on the tracker.
This is a low-level Python wrapper around the JSON-RPC interface offered by the COMET extension of FANUC's web server on R-30iB and R-30iB+ controllers (ie: V8 and up, although older than V9 has a (very) limited interface).
COMET is used by iRProgrammer and a couple of other web-based UIs offered by FANUC on their more recent controller series.
See Requirements for some more information on required options.
NOTE: this is only meant as an example of using COMET's RPC interface.
There is no official documentation on this interface, and it's likely not intended to be used by anything other than FANUC's own products.
Use with caution.
Proper integration of a FANUC controller with an external application or workcell should be done using either the PCDK, RMI (R912), OPC-UA, a fieldbus or similar technology.
The scripts and functionality provided here are only a convenience and are only intended to be used in academic and laboratory settings.
They allow incidental external access to a controller without needing to use any additional hardware.
Do not use this on production systems or in contexts where any kind of determinism is required.
The author recommends using PCDK, RMI, OPC-UA and/or any of the supported fieldbuses in those cases.
- Status
- Requirements
- Compatibility
- Installation
- Example usage
- Supported RPCs
- Limitations / Known issues
- Performance
- Security
- Related projects
- Bugs, feature requests, etc
- FAQ
- Disclaimer
This package is a work-in-progress.
As there is no documentation on COMET, it's been implemented based on information learned from observing iRProgrammer and related web-based UIs.
Expect frequent breakage and missing functionality.
See also the FAQ.
Requirements are a little unclear at this moment, but it appears COMET is installed on all controllers with the base Web Server (HTTP) option and at least V8 of the system software (see notes about Compatibility below).
Interestingly, even though COMET is primarily used by iRProgrammer, option J767 does not appear to be a requirement for it to be installed.
The main other requirement is a functioning networking setup.
Make sure you can ping the controller and the controller's website shows up when opening http://robot_ip in a browser.
Configuration of HTTP Authentication is not needed, as COMET RPCs do not appear to be affected by it (see Security for some more discussion).
Compatibility has only been tested with R-30iB+ controllers running V9.30 and V9.40 of the system software.
It's possible R-30iB with V8.x supports the COMET RPC interface as well, but this has not been tested.
The library has been written for Python version 3. No specific OS dependencies are known, meaning all platforms with a Python 3 interpreter should be supported. Only Windows 10, Ubuntu Bionic and Focal have been extensively tested however.
As the COMET RPC interface is part of the controller's web server, no installation nor setup on the FANUC side should be necessary.
It's recommended to use a virtual Python 3 environment and install the package in it. The author has primarily used Python 3.8, but other versions are expected to work, though they are not actively tested.
Future versions may be released to PyPi.
Example (installs comet_rpc 0.2.4; be sure to update the URL to download the desired version):
python3 -m venv $HOME/venv_comet_rpc
source $HOME/venv_comet_rpc/bin/activate
pip install -U pip
pip install -U wheel setuptools
pip install https://github.com/gavanderhoorn/comet_rpc/archive/0.2.4.tar.gzThe current version of this package does not come with any example scripts. The subsection below is expected to be sufficient to clarify basic usage of the RPC interface.
This resets the controller, sets the override to 100% and finally reads the DO[1] IO port and retrieves its comment:
from comet_rpc import (
exec_kcl,
IoType,
iogetpn,
iovalrd,
vmip_writeva,
)
# IP address or hostname of the R-30iB(+) controller
server = "..."
exec_kcl(server, "reset")
vmip_writeva(server, "*SYSTEM*", "$MCR.$GENOVERRIDE", value=100)
dout1_val = iovalrd(server, IoType.DigitalOut, index=1).value
dout1_cmt = iogetpn(server, IoType.DigitalOut, index=1).value
...Note the lack of error detection and handling to keep the example brief.
The following table shows an overview of known RPCs, whether they are currently supported by comet_rpc (column Supp.?) and which version of COMET appears to support them ("appears", as this information is based on experiments, there is no public, authoritative source of truth available).
The last two columns of the table clarify the minimum version of system software that supports a particular RPC.
An entry in the 8.x column implies an RPC is supported starting with version 8.x.
Use the value in the cell to determine the minor version number.
For RPCs with no information in those columns this information hasn't been determined yet.
Click to expand
| Name | Description | Supp.? | 8.x | 9.x |
|---|---|---|---|---|
| CHGOVRD | Change override | Y | .40+ | |
| CKTRKPRG | Check linetrack attributes | N | .40+ | |
| CLLB_CODE_REQ | N | .40+ | ||
| CLLB_PAYLOAD_CONF | N | .40+ | ||
| CPKCL | Execute KCL command | Y | .30+ | |
| DCS_CHECK_APPLY | N | .40+ | ||
| DCS_CHECK_CODE | N | .40+ | ||
| DCS_VRFY_REQ | N | .40+ | ||
| DPEWRITE_STR | Retrieve error code description | Y | .10+ | |
| DPREAD | Read element from dictionary | Y | .30+ | |
| ERPOST | Post an error to the log | N | .10+ | |
| EXEC_TXCMND | N | .10+ | ||
| GET_FORM | N | .10+ | ||
| GET_RAW_FILE | Get raw byte contents of file | Y | .10+ | |
| GETFOCUS | N | .10+ | ||
| GTFILIST | Get list of files in directory | Y | .40+ | |
| GTMCRLST | Get list of macros | Y | .10+ | |
| GTPIDLST | Get list of posregs in TP program | Y | .40+ | |
| IOASGLOG | Update IO configuration | Y | .40+ | |
| IOCKSIM | Check simulated status of IO port | Y | .30+ | |
| IODEFPN | Set/update comment on IO port | Y | .10+ | |
| IODRYRUN | Treat all IO as-if simulated | N | .40+ | |
| IOGETASG | Retrieve IO configuration | Y | .40+ | |
| IOGETHDB | Retrieve the "HW database" | Y | .40+ | |
| IOGETPN | Retrieve comment on IO port | Y | .10+ | |
| IOGTALL | Read IO ports, batch-wise | Y | .30+ | |
| IOSIM | Set IO port to simulated | Y | .30+ | |
| IOUNSIM | Clear simulated state of IO port | Y | .30+ | |
| IOVALRD | Read IO port | Y | .30+ | |
| IOVALSET | Write to IO port | Y | .30+ | |
| IOWETRUN | Stop treating all IO as simulated | N | .40+ | |
| LOCAL_PAUSE | N | .10+ | ||
| LOCAL_START | Y | .10+ | ||
| MG_RECPOS | N | .40+ | ||
| MMCHGTYP | Change the type of a program | N | .10+ | |
| MMCREMN | Create a TP program | N | .10+ | |
| MMDELPOS | Remove a position from a program | N | .10+ | |
| MMDELPRG | Delete a program | N | .10+ | |
| MMGETATR | Read program attribute | N | .10+ | |
| MMGETTYP | Read 'program type' (TP, PC, etc) | Y | .10+ | |
| MMRENPRG | Rename a program | N | .10+ | |
| MMSETATR | Write program attribute | N | .10+ | |
| MNCHGREP | Convert position representation | N | .10+ | |
| MNCPYPRG | Copy a program | N | .10+ | |
| OSSNDPKT_EXT | N | .10+ | ||
| PASTELIN | Duplicate/move lines in a TP prog | Y | .40+ | |
| PGABORT | Abort all/a specific program(s) | Y | .10+ | |
| PMCUPFN | N | .10+ | ||
| PMCUPRQ | N | .10+ | ||
| PMCVALRD | N | .10+ | ||
| PMON_CAN_PKT | N | .10+ | ||
| PMON_DISCONNECT | N | .10+ | ||
| PMON_GET_PKT | N | .10+ | ||
| PMON_START_MON | N | .10+ | ||
| PMON_STOP_MON | N | .10+ | ||
| PMON_VERIFY_PKT | N | .30+ | ||
| POSREGVALRD | Read a position register | Y | .10+ | |
| RECPOS | Teach position (in program) | N | .10+ | |
| REGVALRD | Read a register (int/real) | Y | .10+ | |
| REMARKLIN | (Un)remark lines in a TP prog | Y | .40/P43+ | |
| RPRINTF | Print to the controllers conslog | Y | .10+ | |
| RUN_TASK | Start a program on the controller | N | .30+ | |
| SCDELETE | Delete line from program | N | .10+ | |
| SCEDIT | Add/replace line to/in program | N | .10+ | |
| SCGETPOS | Get position from program | N | .40+ | |
| SCSETPOS | Update position in program | N | .10+ | |
| SET_FORM | N | .10+ | ||
| SKIP_LINE | Change active line in paused prog | N | .40+ | |
| TPEXTREQ | N | .10+ | ||
| TPLINK_DISCONNECT | N | .10+ | ||
| TPLINK_NEW_URL | N | .10+ | ||
| TPMODE_CHG | N | .40+ | ||
| TPMULTI_TASKIDX | N | .30+ | ||
| TPXENSBV_KRL_EXT | N | .10+ | ||
| TPXENSBV_KRL_TEXT | N | .10+ | ||
| TPXENSUB_EXT | N | .10+ | ||
| TPXFILSB_EXT | N | .10+ | ||
| TPXPRGSB_EXT | N | .10+ | ||
| TXCHGPRG | Open (and make active) a TP prog | Y | .10+ | |
| TXLSTPRG_FC | List programs (specific types) | N | .10+ | |
| TXML_CURANG | Return current joint angles | Y | .10+ | |
| TXML_CURPOS | Return current TCP pose (XYZWPR) | Y | .10+ | |
| TXSETLIN | Open TP prog at specific line | Y | .10+ | |
| VMIP_READVA | Read a (system) variable | Y | .10+ | |
| VMIP_WRITEVA | Write to a (system) variable | Y | .30+ | |
| XMLCOPY | Copy an XML file to another | N | .30+ |
Total supported RPCs: 32 of 85.
Some observations based on the above table:
- IO R/W seems to be officialy supported from
V8.30 - R/W of IO configuration requires at least
V9.40 - writing to (system) variables requires at least
V8.30, but - reading (system) variables requires at least
V9.10 - monitoring of (system) variables requires at least
V8.10 - position and int/real register R/W requires at least
V9.10 - CRUD of TP programs requires at least
V9.10 - interaction with DCS requires at least
V9.40 - starting a program (not via IO) requires at least
V9.30
The following limitations and known issues exist:
COMET(and/or FANUC's web server) seems to return response documents with aContent-type: text/htmlheader. Because of this,comet_rpcjust assumes it receives JSON, even if thecontent-typeheader states otherwise.COMETsometimes returns malformed response documents.comet_rpctries to detect this and either fixes those responses before parsing and validation, or mimics iRProgrammer's behaviour (which is to ignore). This makes some actual errors hard to detect. A better way to deal with this is being investigated.- Only a subset of the RPCs exposed by
COMETis supported by this library. Future updates may add support for more RPCs. - No version checking is implemented (ie:
comet_rpcwill not prevent invoking an RPC on a V8 controller which requires V9) - Reading and writing (system) variables (
vmip_readvaandvmip_writeva) returns and takesstrrepresentations of those variables instead of more specific types as their values. This is partly due to the wayCOMETexpects and returns those values and partly due to limited insight into which types are used by FANUC for those values. Future updates may improve on this.
Even though this library should not be used when performance is a concern, some preliminary figures are presented in this section.
See the following table for an indication of expected RPC performance:
| Platform | SW version | RPC | avg ms/call |
|---|---|---|---|
| RG | V9.30P/26 | IOVALRD | ~8 |
| RG | V9.30P/26 | VMIP_READVA | ~14 |
| R-30iB+ | V9.30P/?? | IOVALRD | ~18 |
Note: this is without connection reuse, as it's unclear whether COMET supports this for regular RPC invocations.
COMET does not appear to be affected by the settings configured under Host Comm, section HTTP Authentication.
No authentication challenges have been observed so far, although that does not mean they are not used.
Some RPCs do appear to require a valid connection id argument, and starting up such a session will lock-out the physical teach pendant with a very clear message shown to operators (stating a "remote pendant" is in use).
comet_rpc does not currently support any RPCs requiring a connection id, nor does it lock-out the physical pendant.
Users concerned about potential undesired and uncontrolled access to the web server and COMET could look into configuring the host blocklist part of the FANUC Server Access Control feature.
It's unclear at this point whether any fine-grained control is possible (ie: allow reads, deny all writes), but blocking unknown hosts from interacting with COMET would be a first step to making it harder to abuse the JSON-RPC interface.
Refer to section 2.5 FANUC SERVER ACCESS CONTROL (FSAC) of the FANUC Robot series - Ethernet Function - Operator's Manual (document B-82974EN for the R-30iA, R-30iB and R-30iB+) for more information.
For a similar library which doesn't use COMET (and is compatible with older controllers), see gavanderhoorn/dominh.
Please use the GitHub issue tracker.
It's likely only intended to be used by FANUC internally in their products. There is no public documentation which mentions it, which implies it's not a public interface.
Apart from the fact that comet_rpc is a work-in-progress at the moment, it makes use of a (most likely) private interface.
This means FANUC has no obligation to maintain compatibility and they are free to change COMET in any way they see necessary without regards for users of this Python library.
Both of these facts make use in production deployments problematic.
See also the NOTE in the Overview section, and Status.
Yes, I agree. See also the NOTE in the Overview section.
Time and application requirements: target framework supported Python, so writing comet_rpc in Python made sense.
Perhaps.
All implemented RPCs so far are executed in a blocking manner on the FANUC side though, with none of the streaming or event-based ones supported (PMON_START_MON et al.).
Future versions may change the default to async while offering a blocking version of the API for bw compatibility.
No.
COMET is an extension to / integrated with the embedded web server running on R-30iB(+) controllers and is a native binary.
It does not use Karel, nor is it run in the Karel VM.
Compared to the PCDK: certainly, but if you need a more performant solution, ask FANUC for a PCDK license or use a fieldbus. If you have ideas on how to improve performance, post an issue on the tracker.
Of course! I can't guarantee I'll have time to work on them though.
Most certainly. As long as new features (or enhancements of existing functionality) pass CI and are reasonably implemented, they will be merged.
gavanderhoorn/dominh is/was an experiment to see whether an RPC library for FANUC controllers could be created with as few required options on the controller as possible.
Because of this, it uses methods which are perhaps not the most efficient (such as Karel programs, KCL and .stm pages), but at least work on as many controllers as possible.
comet_rpc is different: it's a low-level library which directly interfaces with an RPC interface implemented by FANUC, used by some of their web based UIs for CRX robots, iRProgrammer and remote iPendants.
There is no use of Karel, nor KCL.
The only functionality supported is what is offered by COMET and known from looking at iRProgrammer.
Technically, Dominh and comet_rpc could be used at the same time.
It's also likely Dominh will optionally use comet_rpc in the future to make some operations more efficient.
The author of this software is not affiliated with FANUC Corporation in any way. All trademarks and registered trademarks are property of their respective owners, and company, product and service names mentioned in this readme or appearing in source code or other artefacts in this repository are used for identification purposes only. Use of these names does not imply endorsement by FANUC Corporation.