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 ] [ log 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:
http://127.0.0.1:60958/run?command=open+1a0m
Similarly, a system shell command can be used:
curl http://127.0.0.1:60958/run?command=open+1a0s
wget http://127.0.0.1:60958/run?command=open+1grl
The log option indicates whether to show messages from the server in the ChimeraX Log in addition to the client log. With log false (default), the messages will go to the client log only.
If json is false (default), any logging that would normally result from command execution will still occur, but will be shown in the web browser or (for curl or wget) in the shell instead of in the ChimeraX Log. If json is true, command execution will return a string in JSON (JavaScript Object Notation) format representing a JSON “object” with the following name/value pairs:
| Name | Value |
|---|---|
| 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 null for commands that have not yet implemented JSON return values. |
log messages | A JSON object with the names corresponding to chimerax.core.logger.Log.LEVEL_DESCRIPTS and whose values are lists of messages logged at that level during command execution. |
error | If the commands execute without raising an error, this will be null. Otherwise, it will be a JSON object with two names, type and message, with values that are the Python class name for the error (e.g. ValueError) and the error message text, respectively. In this case the “python values” and “json values” lists will be empty. |
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.