Skip to content

protocol

Jump to bottom Edit New page
mdavidsaver edited this page Jun 27, 2019 · 41 revisions

pvAccess Protocol Specification

EPICS v4 Working Group

This document was converted from the Public Working Draft, 16-October-2015, http://epics-pvdata.sourceforge.net/pvAccess_Protocol_Specification.html and continues to be updated.

  • Editors:
    Matej Sekoranja, Cosylab Marty Kraimer, BNL Greg White, SLAC, PSI Andrew Johnson, APS (Invited Expert) Benjamin Franksen, HZB (Invited Expert) Michael Abbott, DLS (Invited Expert) Philip Duval, DESY (Invited Expert)

Abstract

This document defines the EPICS communication protocol called "pvAccess". pvAccess is a high-performance network communication protocol for signal monitoring and scientific data services interconnect. It also encompasses a structured data encoding referred to as "pvData".

The connection setup requirements and individual message constructs of pvAccess are described. It is intended that sufficient detail is given for a reader to create an interoperable pvAccess implementation.

EPICS is a computer platform for building the control systems of large scientific instruments. For more information about EPICS, please refer to the home page of the Experimental Physics and Industrial Control System.

Status of this Document

Missing aspects of this specification are described in the last section at the end of this document. It is expected that the next draft will address these remaining items as a Last Call draft, and be followed by publication of the specification.

The present implementation of pvAccess largely reflects the specification as written here. Another document will soon be written to track the status of the reference implementation with respect to the specification, showing what has yet to be implemented.

The terms MUST, MUST NOT, SHOULD, SHOULD NOT, REQUIRED, and MAY when highlighted (through style sheets, and in uppercase in the source) are used in accordance with RFC 2119 [RFC2119]. The term NOT REQUIRED (not defined in RFC 2119) indicates exemption.

In general the text in this document is intended to be "normative", which is to say it constitutes a formal specification of protocol itself. As such that text is concise, algorithmic, and describes the protocol systematically. Such text is in the default font of the document. The functional consequences of the specification so described, although not normative, may be important. Such non-normative text is in italics.

Protocol Versions

This section describes protocol variations based on negotiated version. The remote peer should be assumed to be Version 1 until the first message is received and decoded. After this point, the negotiated version is the lesser of the local and peer versions.

As a special exception, a TCP peer must be disconnected if it does not send a valid message within '$EPICS_PVA_CONN_TMO' seconds.

Version 2

  • v2 server's 'Echo' reply must include the request payload.
  • v2 peers must close TCP connections when no data has been received in '$EPICS_PVA_CONN_TMO' seconds (default 30 sec.).
  • v2 clients must send 'Echo' more often than '$EPICS_PVA_CONN_TMO' seconds. The recommended interval is half of '$EPICS_PVA_CONN_TMO' (default 15 sec.).

Version 1

  • v1 servers reply to 'Echo' with empty payload.
  • v1 clients never send 'Echo'.
  • v1 peers never timeout inactive TCP connections.

Version 0

  • Obsolete version code used by early clients/servers. Messages are not compatible with >=v1.

Table of Contents

  1. Overview
  2. Data Encoding
  3. Connection Management
  4. Channel Life-cycle
  5. Channel Request Life-cycle
  6. Flow Control
  7. Channel Discovery
  8. Communication Example
  9. Protocol Messages
    1. Message header
  10. Application Messages
    1. Beacon (0x00)
    2. Connection validation (0x01)
    3. Echo (0x02)
    4. Search request (0x03)
    5. Search response (0x04)
    6. Create channel (0x07)
    7. Destroy channel (0x08)
    8. Channel get (0x0A)
    9. Channel put (0x0B)
    10. Channel put-get (0x0C)
    11. Channel monitor (0x0D)
    12. Channel array (0x0E)
    13. Destroy request (0xF)
    14. Channel process (0x10)
    15. Get channel type introspection data (0x11)
    16. Message (0x12)
    17. Channel RPC (0x14)
    18. Cancel request (0x15)
    19. Origin Tag (0x16)
  11. Control Messages
    1. Mark Total Byte Sent (0x00)
    2. Acknowledge Total Bytes Received (0x01)
    3. Set byte order (0x02)
    4. Echo request (0x03)
    5. Echo response (0x04)
  12. Future Protocol Changes/Updates
  13. Missing Aspects

Overview

pvAccess is a high-performance network communication protocol. It is designed for efficient signal monitoring and the data requirements of a service oriented architecture.

pvAccess is a successor of EPICS Channel Access bib:caref.

TCP/IP is used for data transmission. UDP/IP is normally used for discovery, although discovery over TCP/IP is also allowed. The discovery mechanism allows the use of other implementations (e.g. UDP/IP for data transmission).

Port number 5076 is used for UDP traffic by default. Port number 5075 is preferred for TCP connections, but a random port can be used.

To support multiple local sockets at port 5076 to able all to receive unicast messages over the UDP a multicast group on local network interface at address 224.0.0.128, port 5076, is used. Any UDP message flagged as unicast received at port 5076 MUST be forwarded to the multicast group with unicast flag cleared.

The pvAccess protocol definition consists of three major parts:

  • A set of data encoding rules that determine how the various data types are encoded and deserialized
  • A set of rules that determine how client and server agree on a particular encoding
  • A number of message types, that define the interchange between endpoints, together with rules which specify what message is to be sent under what circumstances.

Future Protocol Changes/Updates

The following are known items that should be specified in future revisions:

  • "one-phase" get/put/get-put/process
  • immutable fields support, cache implemented for values (useful for enums)
  • optimized packed Monitor responses
  • bulk message transfer/trottle public API
  • access rights
  • etc.

Missing Aspects

The following aspects are missing in the current revision of the specification and will be specified in future revisions:

  • structure/content of pvRequestIF/pvRequest fields
  • offset and count fields of channelArray request should be of type 'size', however 'size' cannot be negative
  • update Communication Example section to show messages

Bibliography

bib:caref

EPICS R3.14 Channel Access Reference Manual, J.O. Hill, R. Lange, 2002, http://www.aps.anl.gov/epics/base/R3-14/8-docs/CAref.html

bib:pvdatarefcpp

EPICS pvDataCPP [pvData C++ Programmers Reference Manual], M. Kraimer, 2011 under development, http://epics-pvdata.sourceforge.net/docbuild/pvDataCPP/tip/documentation/pvDataCPP.html

bib:pvdatarefjava

EPICS pvDataJava [pvData Java Programmers Reference Manual], M. Kraimer, 2011 under development, http://epics-pvdata.sourceforge.net/docbuild/pvDataJava/tip/documentation/pvDataJava.html

bib:ieee754wiki

IEEE 754-2008, Wikipedia article, April 2012, http://en.wikipedia.org/wiki/IEEE_754-1985

Add a custom footer
Add a custom sidebar
Clone this wiki locally