PHD2 allows programs to actively monitor guiding status and control PHD2. This allows clients to do things like:

• graph PHD2 guide data in real time
• monitor PHD2 for exceptional events like guiding lost, and send an alert when something goes wrong
• control PHD2 from an imaging application

This document describes the communication protocol for interacting programmatically with PHD2.

If you are looking for ready-to-use code that implements this communication protocol, please see this repo PHD2 API Client Code.

Clients connect to PHD2 on TCP port 4400. When multiple PHD instances are running, each instance listens on successive port numbers (4401, 4402, ...).

PHD allows multiple clients to establish connections simultaneously.

When a client establishes a connection, PHD sends a series of event notification messages to the client (see #Initial_Messages). Then, as guiding events take place in PHD, notification messages are sent to all connected clients.

Event Notification messages are formatted as JSON objects. Each message is a single line of text terminated by CR LF.

All messages contain the following attributes in common:

Here are the available messages and the attributes of each message.

Describes the PHD and message protocol versions.

Example

{"Event":"Version","Timestamp":1372082668.897,"Host":"AGALASSO","Inst":1,"PHDVersion":"2.0.4","PHDSubver":"a","MsgVersion":1}

The lock position has been established.

Calibration step

Calibration completed successfully.

A star has been selected.

Guiding begins.

(no message attributes)

Guiding has been paused.

Calibration begins.

The state attribute can be one of the following:

The AppState notification is only sent when the client first connects to PHD2 (see #Initial_Messages). If an application would like to maintain an up-to-date AppState status, it will need to update its notion of AppState by handling individual notification events as follows:

Calibration failed.

Calibration data has been flipped.

The lock position shift is active and the lock position has shifted to the edge of the field of view.

(no event attributes)

Sent for each exposure frame while looping exposures.

Looping exposures has stopped.

(no event attributes)

Sent when settling begins after a dither or guide method invocation.

(no event attributes)

Sent for each exposure frame after a dither or guide method invocation until guiding has settled.

Sent after a dither or guide method invocation indicating whether settling was achieved, or if the guider failed to settle before the time limit was reached, or if some other error occurred preventing guide or dither to complete and settle.

A frame has been dropped due to the star being lost.

Guiding has stopped.

(no event attributes)

PHD has been resumed after having been paused.

(no attributes)

This event corresponds to a line in the PHD Guide Log. The event is sent for each frame while guiding.

The lock position has been dithered.

The lock position has been lost.

(no attributes)

An alert message was displayed in PHD2.

A guiding parameter has been changed.

Notification sent when any settings are changed -- allows a client to keep in sync with PHD2 configuration settings by exporting settings only when required.

(no event attributes)

When a client first connects, PHD sends a series of event messages to the client. The first event is

• Version Then, one or more of
• LockPositionSet
• StarSelected
• CalibrationComplete
• StartGuiding, StartCalibration, or Paused depending on the state of PHD.

Finally, PHD will send

• AppState

PHD2 provides an RPC (remote procedure call) interface for event server clients. The message protocol is JSON RPC 2.0.

Requests are sent as a single line of text, terminated by CR LF. Responses from the server are also a single line of text terminated by CR LF.

Here is an example exchange between client (-->) and server (<--):

Get current camera exposure time:

--> {"method": "get_exposure", "id": 1}
<-- {"jsonrpc": "2.0", "result": 1000, "id": 1}

Set camera exposure:

--> {"method": "set_exposure", "params": [1500], "id": 2}
<-- {"jsonrpc": "2.0", "result": 0, "id": 2}

Set camera exposure (error):

--> {"method": "set_exposure", "params": [1502], "id": 3}
<-- {"jsonrpc": "2.0", "error": {"code": 1, "message": "could not set exposure duration"}, "id": 3}

The SETTLE parameter is used by the guide and dither commands to specify when PHD2 should consider guiding to be stable enough for imaging. SETTLE is an object with the following attributes:

• pixels - maximum guide distance for guiding to be considered stable or "in-range"
• time - minimum time to be in-range before considering guiding to be stable
• timeout - time limit before settling is considered to have failed

So, for example, to request settling at less than 1.5 pixels for at least 10 seconds, with a time limit of 60 seconds, the settle object parameter would be:

{"pixels": 1.5, "time": 10, "timeout": 60}

The guide method allows a client to request PHD2 to do whatever it needs to start guiding and to report when guiding is settled and stable.

When the guide method command is received, PHD2 will respond immediately indicating that the guide sequence has started. The guide method will return an error status if equipment is not connected. PHD will then:

• start capturing if necessary
• auto-select a guide star if one is not already selected. It the optional ROI parameter is present, star selection will be confined to the specified region of interest.
• calibrate if necessary, or if the recalibrate parameter is true
• wait for calibration to complete
• start guiding if necessary
• wait for settle (or timeout)
• report progress of settling for each exposure (send Settling events)
• report success or failure by sending a SettleDone event.

If the guide command is accepted, PHD is guaranteed to send a SettleDone event some time later indicating the success or failure of the guide sequence. Note: if PHD2 is already guiding, the 'guide' RPC will only trigger another settling period - it will not stop and restart guiding. To "start fresh" with guiding, first transmit the 'stop_capture' RPC, then transmit the 'guide' RPC.

Example

{"method": "guide", "params": {"settle": {"pixels": 1.5, "time": 8, "timeout": 40}}, "id": 42}

Example showing optional recalibrate and roi params

{"method": "guide", "params": {"settle": {"pixels": 1.5, "time": 8, "timeout": 40}, "recalibrate": false, "roi": [20, -50, 1280, 960]}, "id": 42}

The dither method allows the client to request a random shift of the lock position by +/- PIXELS on each of the RA and Dec axes. If the RA_ONLY parameter is true, or if the Dither RA Only option is set in the Brain, the dither will only be on the RA axis. The PIXELS parameter is multiplied by the Dither Scale value in the Brain.

Like the guide method, the dither method takes a SETTLE object parameter. PHD will send Settling and SettleDone events to indicate when guiding has stabilized after the dither.

Example

{"method": "dither", "params": {"amount": 10, "raOnly": false, "settle": {"pixels": 1.5, "time": 8, "timeout": 40}}, "id": 42}

1. Any of the PHD2 RPC commands that include a settling parameter can trigger long-running

operations. For example, a 'guide' command may result in an extended sequence of looping,

auto-selection, calibration, start of guiding, and settling. If the application sends another RPC that

can affect these state transitions before the first operation is completed, it may get an error return

message about "re-entrancy". For example, issuing a command like 'dither' while a previous

settling event is still ongoing will result in an error return, and the dither will not be done. It is the

responsibility of the application to monitor the PHD2 events and state-changes after starting one

of these long-running operations. The best practice is to wait until the 'SettleDone' message has

been received, at which point the long-running operation has completed.

2. Although the available RPC commands permit a fine-grained control over PHD2 operations, it is

generally a poor practice to "micro-manage" the application. For example, forcing calibrations or

flipping calibration data is normally unnecessary and adds confusion for the end-user. These

things should be done only in special circumstances, not as a lazy "lowest-common-denominator"

approach. Unnecessary calibrations, in particular, can be burdensome to end-users because

lower-end mounts often need to have Dec backlash cleared manually in order for the calibration

to get an accurate result.