The remotecontrol command allows other applications to send commands to an already running instance of ChimeraX. Either of the following methods of communication can be used:
Usage: remotecontrol rest start [ port N ] [ ssl true | false ] [ json true | false ]
Usage: remotecontrol rest stop [ quiet true | false ]
Usage: remotecontrol rest port
The REST method (representational state transfer) is used by web browsers and shell commands such as curl and wget. The commands are sent by http (ssl false, default) or https (ssl true) requests. The command remotecontrol rest start option allows ChimeraX to accept commands by this method. The port number can be specified or chosen randomly; integers in the range 1024-65535 are allowed, but values 49152-65535 are preferable because the lower numbers are registered for various services and could be unavailable. The localhost address (IP 127.0.0.1) is reported automatically along with the port number in the Log when REST communication is started, and can be reported later with the command remotecontrol rest port. If the port number is 60958 (for example), a web browser can send a ChimeraX command with an URL something like:
Similarly, a system shell command can be used:
|python values||A list of the Python values returned by the commands executed. Typically, the list would contain only one value, but if the “command” sent was actually a series of commands separated by semicolons, the list would contain the corresponding number of values.||json values||A list of the JSON values returned by the commands executed. The exact contents of a command's JSON value should be provided in the doc string for the function that carries out the corresponding command. The value will be
||log messages||A JSON object with the names corresponding to
||error||If the commands execute without raising an error, this will be
The command remotecontrol rest stop discontinues accepting commands by REST, optionally sending a notification to the Log (quiet false, default).
Usage: remotecontrol xmlrpc on [ address IP-address ] [ port N ] [ timeout s ]
Usage: remotecontrol xmlrpc off
The XML-RPC method (extensible markup language remote procedure call) is used by Python scripts or applications. The command remotecontrol xmlrpc on (synonyms for on are true, True, 1) allows ChimeraX to receive instructions in this way, with optional specification of the port number (default 42184). The IP-address should be that of the computer running ChimeraX (default 127.0.0.1, localhost, recommended to prevent other computers from sending commands).
The ChimeraX remote_control bundle includes an example python2 script that sends commands to ChimeraX using XML-RPC via port number 42184:
python2 /Applications/ChimeraX.app/Contents/lib/python3.7/site-packages/chimerax/remote_control/run.py "open 1a0m"
This method of communication does not return log output, just a true/false status of whether the command succeeded. The timeout period s (default 10.0 seconds) is how long ChimeraX should wait after trying to report that status to the other application. The command remotecontrol xmlrpc off (synonyms for off are false, False, 0) discontinues accepting commands by XML-RPC.