Home

Pycaserver Documentation

Channel Access Websockets API

The EPICS Channel Access API is used to monitor PVs.

Establishing a Websockets Connection

Before you can interact with PVs, you need to establish a websockets connection to the server. You only need one connection to the server, regardless of how many PVs you want to connect to. Establish a connection using the /monitor URL. In javascript, this looks like:

var ws = new WebSocket("ws://localhost:8888/monitor");

Once you've connected, you interact with the server by sending and receiving JSON messages. All messages you send will have an "action" property which tells the server what you want to do. Other properties vary depending on the action. Continuing the javascript example, you'd want to do something like this:

var msg = JSON.stringify({ "action":"connect", "pv":"myPVName" });
ws.send(msg);

The server will send you JSON messages in response to your actions. Server messages have a "msg_type" property which describes the type of response you are receiving. Other properties vary depending on the message type. Messages look something like this:

{ "msg_type": "connection", "pvname": "myTest:PV", "conn": True }

In javascript, you handle messages by adding an onmessage callback function to your websockets connection:

ws.onmessage = function(event) {
  var msg = JSON.parse(event.data);
  //Do something with the message you received
  console.log(msg["msg_type"]);
}  

Connecting to PVs

To connect to a PV, send a message with the "connect" action:

{ "action":"connect", "pv": "myTest:PV" }

Connection messages only have one parameter - pv, which is a string with the name of the PV you want to connect to.

Once you've sent the request, the server will establish a channel access subscription to the PV. Once the PV is connected, you'll get a response back:

{ "msg_type": "connection", "pvname": "myTest:PV", "conn": True }

Connection messages always have a pvname property which lists the PV for which this message is relevant, and a conn property which contains a boolean. True indicates a the connection is established. If the PV disconnects for any reason, another connection message will be sent with conn set to False.

Receiving PV data

Once you've connected to a PV, you can expect to receive messages from the server whenever the value of the PV changes (or whenever the IOC feels like broadcasting the value of the PV). The data messages look like this:

{ "msg_type": "monitor", "pvname": "myTest:PV", "value": 5, "count": 1, "timestamp": 1447799204, "units": "egu" }

Monitor messages will always list the pvname, and the latest value of the PV. The type of value is usually related to the PV's native type: numeric types like doubles and ints will be javascript numbers, strings will be javascript strings. Waveform PVs will have an array type value. The count property describes the size of the array, if this is a waveform PV. Scalar PVs will always have a count of 1. timestamp is a UNIX timestamp for this update. units is a string describing the units for this PV, if available.

Disconnecting from PVs

If you no longer want monitor updates from a PV, send a message with the "disconnect" action:

{ "action":"disconnect", "pv": "myTest:PV" }

Your disconnect request only needs one parameter: pv, which is the name of the PV you wish to disconnect from. Disconnection requests for PVs which you do not have a connection to are silently ignored.