PyEpics: Epics Channel Access for Python

# PV: Epics Process Variables

The `pv` module provides a higher-level class `pv.PV`, which creates a PV object for an EPICS Process Variable. A PV object has both methods and attributes for accessing it’s properties.

## The `PV` class

class pv.PV(pvname[, callback=None[, form='time'[, verbose=False[, auto_monitor=None[, count=None[, connection_callback=None[, connection_timeout=None[, access_callback=None]]]]]]]])
create a PV object for a named Epics Process Variable.
  Parameters:

    - pvname – name of Epics Process Variable

    - callback (callable, tuple, list or None) – user-defined callback function on changes to PV value or state.

    - form (string, one of ('native','ctrl', or 'time')) – which epics data type to use: the ‘native’, ‘time’, or the ‘ctrl’ (Control) variant.

    - verbose (`True`/`False`) – whether to print out debugging messages

    - auto_monitor (`None`, `True`, `False`, or bitmask (see Automatic Monitoring of a PV)) – whether to automatically monitor the PV for changes.

    - count (int) – number of data elements to return by default (see here)

    - connection_callback (callable or `None`) – user-defined function called on changes to PV connection status.

    - connection_timeout (float or `None`) – time (in seconds) to wait for connection before giving up

    - access_callback (callable or `None`) – user-defined function called on changes to PV access rights

Once created, a PV should (barring any network issues) automatically connect and be ready to use.

    >>> from epics import PV
    >>> p = PV('XX:m1.VAL')
    >>> print(p.get())
    >>> print(p.count, p.type)

The pvname is required, and is the name of an existing Process Variable.

The callback parameter specifies one or more python methods to be called on changes, as discussed in more detail at User-supplied Callback functions

The connection_callback parameter specifies a python method to be called on changes to the connection status of the PV (that is, when it connects or disconnects). This is discussed in more detail at User-supplied Connection Callback functions

The form parameter specifies which of the three variants ‘native’, ‘ctrl’ (Control) or ‘time’ (the default) to use for the PV. The ‘native’ form returns just the value, the ‘time’ form includes the timestamp from the server the PV lives on, as well as status information. The control form includes several additional fields such as limits to the PV, which can be useful in some cases. Also note that the additional ‘ctrl’ value fields (see the Table of Control Attributes) can be obtained with `get_ctrlvars()` even for PVs of ‘native’ or ‘time’ form.

The auto_monitor parameter specifies whether the PV should be automatically monitored. See Automatic Monitoring of a PV for a detailed description of this.

The verbose parameter specifies more verbose output on changes, and is intended for debugging purposes.

The access_callback parameter specifies a python method to be called on changes to the access rights of the PV (read/write access changes). This is discussed in more detail here.

### methods

A PV has several methods for getting and setting its value and defining callbacks to be executed when the PV changes.

pv.get([count=None[, as_string=False[, as_numpy=True[, timeout=None[, use_monitor=True[, with_ctrlvars=False]]]]]])

  get and return the current value of the PV

  Parameters:

    - count (integer or `None`) – maximum number of array elements to return

    - as_string (`True`/`False`) – whether to return the string representation of the value.

    - as_numpy – whether to try to return a numpy array where appropriate.

    - timeout (float or `None`) – maximum time to wait for data before returning `None`.

    - use_monitor (`True`/`False`) – whether to rely on monitor callbacks or explicitly get value now.

  see String representation for a PV for details on how the string representation is determined.

  With the as_numpy option, an array PV (that is, a PV whose value has more than one element) will be returned as a numpy array, provided the numpy module is available. See Strategies for working with large arrays for a discussion of strategies for how to best deal with very large arrays.

  The use_monitor option controls whether the most recent value from the automatic monitoring will be used or whether the value will be explicitly asked for right now. Usually, you can rely on a PVs value being kept up to date, and so the default here is `True`. But, since network traffic is not instantaneous and hard to predict, the value returned with use_monitor=True may be out-of-date.

  The timeout sets how long (in seconds) to wait for the value to be sent. This only applies with use_monitor=False, or if the PV is not automatically monitored. Otherwise, the most recently received value will be sent immediately.

  The with_ctrlvars option requests DBR_CTRL data, including control limits, precision, and so on, in addition to the value normally returned. This metadata will be available by accessing various attributes such as `lower_ctrl_limit`.

  See Automatic Monitoring of a PV for more on monitoring PVs and The wait and timeout options for get(), ca.get_complete() for more details on what happens when a `pv.get()` times out.

pv.get_with_metadata([form=None[, count=None[, as_string=False[, as_numpy=True[, timeout=None[, use_monitor=True[, with_ctrlvars=False]]]]]]])

  Returns a dictionary of the current value and associated metadata

  Parameters:

    - form ({'native', 'time', 'ctrl', None}) – EPICS data type to request: the ‘native’, or the ‘ctrl’ (Control) or ‘time’ variant. Defaults to the PV instance attribute `form`.

    - count (integer or `None`) – maximum number of array elements to return

    - as_string (`True`/`False`) – whether to return the string representation of the value.

    - as_numpy – whether to try to return a numpy array where appropriate.

    - timeout (float or `None`) – maximum time to wait for data before returning `None`.

    - use_monitor (`True`/`False`) – whether to rely on monitor callbacks or explicitly get value now.

  See `PV.get`, above, for further notes on each of these parameters.

  Each request to EPICS can optionally contain additional metadata associated with the value. While `PV.get` updates the PV instance with any metadata, `get_with_metadata` will return the requested metadata and value in a dictionary.

  The exception is when the PV is set to auto-monitor and the use_monitor parameter here is set. This means that both the value and metadata will used the cached values instead of making a new request. Because of this, the metadata and value returned here will be a full dictionary of all known metadata for the PV instance.

pv.put(value[, wait=False[, timeout=30.0[, use_complete=False[, callback=None[, callback_data=None]]]]])

  set the PV value, optionally waiting to return until processing has completed, or setting the `put_complete` to indicate complete-ness.

  Parameters:

    - value – value to set PV

    - wait (`True`/`False`) – whether to wait for processing to complete (or time-out) before returning.

    - timeout (float) – maximum time to wait for processing to complete before returning anyway.

    - use_complete (`True`/`False`) – whether to use a built-in callback to set `put_complete`.

    - callback (`None` or a valid python function) – user-supplied function to run when processing has completed.

    - callback_data – extra data to pass on to a user-supplied callback function.

The wait and callback arguments, as well as the ‘use_complete’ / `put_complete` attribute give a few options for knowing that a `put()` has completed. See Put with wait, put callbacks, and put_complete for more details.

pv.get_ctrlvars()

  returns a dictionary of the control values for the PV. This dictionary may have many members, depending on the data type of PV. See the Table of Control Attributes for details.

pv.get_timevars()

  returns a dictionary of the time values for the PV, which include status, severity, and the timestamp from the CA server.

pv.poll([evt=1.e-4[, iot=1.0]])

  poll for changes. This simply calls `epics.ca.poll()`

  Parameters:

    - evt (float) – time to pass to `epics.ca.pend_event()`

    - iot (float) – time to pass to `epics.ca.pend_io()`

pv.connect([timeout=None])

  this explicitly connects a PV, and returns whether or not it has successfully connected. It is probably not that useful, as connection should happen automatically. See `wait_for_connection()`.

  Parameters:

    timeout (float) – maximum connection time, passed to `epics.ca.connect_channel()`

  Return type:

    `True`/`False`

  if timeout is `None`, the PVs connection_timeout parameter will be used. If that is also `None`, `episc.ca.DEFAULT_CONNECTION_TIMEOUT` will be used.

pv.wait_for_connection([timeout=None])

  this waits until a PV is connected, or has timed-out waiting for a connection. Returns whether the connection has occurred.

  Parameters:

    timeout (float) – maximum connection time.

  Return type:

    `True`/`False`

  if timeout is `None`, the PVs connection_timeout parameter will be used. If that is also `None`, `epics.ca.DEFAULT_CONNECTION_TIMEOUT` will be used.

pv.disconnect()

  disconnect a PV, clearing all callbacks.

pv.reconnect()

  reconnect (or try to) a disconnected PV.

pv.clear_auto_monitor()

  turn off automatic monitoring of a PV. Note that this will suspend all event callbacks on a PV at the CA level by calling `epics.ca.clear_subscription()`, but will not clear the list of PVs callbacks. This means that doing `reconnect()` will resume event processing including any callbacks or the PV.

pv.add_callback(callback=None[, index=None [, with_ctrlvars=True[, **kw]])

  adds a user-defined callback routine to be run on each change event for this PV. Returns the integer index for the callback.

  Parameters:

    - callback (`None` or callable) – user-supplied function to run when PV changes.

    - index (`None` (integer will be produced) or immutable) – identifying key for this callback

    - with_ctrlvars – whether to (try to) make sure that accurate `control values` will be sent to the callback.

    - kw – additional keyword/value arguments to pass to each execution of the callback.

  Return type:

    integer

  Note that multiple callbacks can be defined, each having its own index (a dictionary key, typically an integer). When a PV changes, all the defined callbacks will be executed. They will be called in order (by sorting the keys of the `callbacks` dictionary)

  See also: `callbacks` attribute, User-supplied Callback functions

pv.remove_callback(index=None)

  remove a user-defined callback routine using supplied

  Parameters:

    index (`None` or integer) – index of user-supplied function, as returned by `add_callback()`, and also to key for this callback in the `callbacks` dictionary.

  Return type:

    integer

  If only one callback is defined an index=``None``, this will clear the only defined callback.

  See also: `callbacks` attribute, User-supplied Callback functions

pv.clear_callbacks()

  remove all user-defined callback routine.

pv.run_callbacks()

  execute all user-defined callbacks right now, even if the PV has not changed. Useful for debugging!

  See also: `callbacks` attribute, User-supplied Callback functions

pv.run_callback(index)

  execute a particular user-defined callback right now, even if the PV has not changed. Useful for debugging!

  See also: `callbacks` attribute, User-supplied Callback functions

pv.force_read_access_rights()

  force a read of the access rights for a PV. Normally, a PV will have access rights determined automatically and subscribe to changes in access rights. But sometimes (especially 64-bit Windows), the automatically reported values are wrong. This methods will explicitly read the access rights.

### attributes

A PV object has many attributes, each associated with some property of the underlying PV: its value, host, count, and so on. For properties that can change, the PV attribute will hold the latest value for the corresponding property, Most attributes are read-only, and cannot be assigned to. The exception to this rule is the `value` attribute.

pv.value

  The current value of the PV.

  Note: The `value` attribute can be assigned to. When read, the latest value will be returned, even if that means a `get()` needs to be called.

  Assigning to `value` is equivalent to setting the value with the `put()` method.

      >>> from epics import PV
      >>> p1 = PV('xxx.VAL')
      >>> print(p1.value)
      1.00
      >>> p1.value = 2.00

pv.char_value

  The string representation of the string, as described in `get()`.

pv.status

  The PV status, which will be 0 for a normal, connected PV.

pv.type

  string describing data type of PV, such as double, float, enum, string, int, long, char, or one of the ctrl or time variants of these, which will be named ctrl_double, time_enum, and so on. See the Table of DBR Types

pv.ftype

  The integer value (from the underlying C library) indicating the PV data type according to Table of DBR Types

pv.host

  string of host machine provide this PV.

pv.count

  number of data elements in a PV. 1 except for waveform PVs, where it gives the number of elements in the waveform. For recent versions of Epics Base (3.14.11 and later?), this gives the .NORD field, which gives the number of elements last put into the PV and which may be less than the maximum number allowed (see nelm below).

pv.nelm

  number of data elements in a PV. 1 except for waveform PVs where it gives the maximum number of elements in the waveform. For recent versions of Epics Base (3.14.11 and later?), this gives the .NELM parameter. See also the count attribute above.

pv.read_access

  Boolean (`True`/`False`) for whether PV is readable

pv.write_access

  Boolean (`True`/`False`) for whether PV is writable

pv.access

  string describing read/write access. One of ‘read/write’,’read-only’,’write-only’, ‘no access’.

pv.severity

  severity value of PV. Usually 0 for PVs that are not in an alarm condition.

pv.timestamp

  floating point timestamp (relative to the POSIX time origin, not the EPICS time origin) of the last event seen for this PV. Note that this is will contain the timestamp from the Epics server if the PV object was created with the `form='time'` option. Otherwise, the timestamp will be set to time according to the client, indicating when the data arrive from the server.

pv.posixseconds

  Integer number of seconds (relative to the POSIX time origin, not the EPICS time origin) of the last event seen for this PV. This will be set only if the PV object was created with the `form='time'` option, and will reflect the timestamp from the server. Otherwise, this value will be 0 which can be used to signal that the timestamp attribute is from the client.

pv.nanoseconds

  Integer number of nanoseconds for the last event seen for this PV. This will be set only if the PV object was created with the `form='time'` option, and will give higher time resolution than the timestamp attribute.

pv.precision

  number of decimal places of precision to use for float and double PVs

pv.units

  string of engineering units for PV

pv.enum_strs

  a list of strings for the enumeration states of this PV (for enum PVs)

pv.info

  a string paragraph (ie, including newlines) showing much of the information about the PV.

pv.upper_disp_limit

pv.lower_disp_limit

pv.upper_alarm_limit

pv.lower_alarm_limit

pv.lower_warning_limit

pv.upper_warning_limit

pv.upper_ctrl_limit

pv.lower_ctrl_limit

  These are all the various kinds of limits for a PV.

pv.put_complete

  a Boolean (`True`/`False`) value for whether the most recent `put()` has completed.

pv.callbacks

  a dictionary of currently defined callbacks, to be run on changes to the PV. This dictionary has integer keys (generally in increasing order of when they were defined) which sets which order for executing the callbacks. The values of this dictionary are tuples of (callback, keyword_arguments).

  Note: The `callbacks` attribute can be assigned to or

    manipulated directly. This is not recommended. Use the methods `add_callback()`, `remove_callback()`, and `clear_callbacks()` instead of altering this dictionary directly.

pv.connection_callbacks

  a simple list of connection callbacks: functions to be run when the connection status of the PV changes. See User-supplied Connection Callback functions for more details.

pv.access_callbacks

  an `list` of access callbacks: functions to be run when the access rights of the PV changes. See User-supplied Access Rights Callback functions for more details.

## String representation for a PV

The string representation for a PV, as returned either with the as_string argument to `epics.ca.get()` or from the `char_value` attribute (they are equivalent) needs some further explanation.

The value of the string representation (hereafter, the `char_value`), will depend on the native type and count of a PV. Table of String Representations

> Table of String Representations: How raw data `value` is mapped to `char_value` for different native data types.

> > data types | count | char_value
> > --- | --- | ---
> > string | 1 | = value
> > char | 1 | = value
> > short | 1 | = str(value)
> > long | 1 | = str(value)
> > enum | 1 | = enum_str[value]
> > double | 1 | = (“%%.%if” % (precision)) % value
> > float | 1 | = (“%%.%if” % (precision)) % value
> > char | > 1 | = long string from bytes in array
> > all others | > 1 | = <array size=*count*, type=*type*>

For double/float values with large exponents, the formatting will be (“%%.%ig” % (precision)) % value. For character waveforms (char data with count > 1), the `char_value` will be set according to:

    >>> firstnull  = val.index(0)
    >>> if firstnull == -1: firstnull= len(val)
    >>> char_value = ''.join([chr(i) for i in val[:firstnull]).rstrip()

## Automatic Monitoring of a PV

When creating a PV, the auto_monitor parameter specifies whether the PV should be automatically monitored or not. Automatic monitoring means that an internal callback will be registered for changes. Any callbacks defined by the user will be called by this internal callback when changes occur.

For most scalar-value PVs, this automatic monitoring is desirable, as the PV will see all changes (and run callbacks) without any additional interaction from the user. The PV’s value will always be up-to-date and no unnecessary network traffic is needed.

Possible values for `auto_monitor` are:

`False`

  For some PVs, especially those that change much more rapidly than you care about or those that contain large arrays as values, auto_monitoring can add network traffic that you don’t need. For these, you may wish to create your PVs with auto_monitor=False. When you do this, you will need to make calls to `get()` to explicitly get the latest value.

`None`

  The default value for auto_monitor is `None`, and is set to `True` if the element count for the PV is smaller than `epics.ca.AUTOMONITOR_MAXLENGTH` (default of 65536). To suppress monitoring of PVs with fewer array values, you will have to explicitly turn auto_monitor to `False`. For waveform arrays with more elements, automatic monitoring will not be done unless you explicitly set auto_monitor=True, or to an explicit mask. See Strategies for working with large arrays for more details.

`True`

  When auto_monitor is set to `True`, the value will be monitored using the default subscription mask set at `epics.ca.DEFAULT_SUBSCRIPTION_MASK`.

  This mask determines which kinds of changes cause the PV to update. By default, the subscription updates when the PV value changes by more than the monitor deadband, or when the PV alarm status changes. This behavior is the same as the default in EPICS’ camonitor tool.

Mask

  It is also possible to request an explicit type of CA subscription by setting auto_monitor to a numeric subscription mask made up of dbr.DBE_ALARM, dbr.DBE_LOG and/or dbr.DBE_VALUE. This mask will be passed directly to `epics.ca.create_subscription()` An example would be:

      pv1 = PV('AAA', auto_monitor=dbr.DBE_VALUE)
      pv2 = PV('BBB', auto_monitor=dbr.DBE_VALUE|dbr.DBE_ALARM)
      pv3 = PV('CCC', auto_monitor=dbr.DBE_VALUE|dbr.DBE_ALARM|dbr.DBE_LOG)

  which will generate callbacks for pv1 only when the value of ‘AAA’ changes, while pv2 will receive callbacks if the value or alarm state of ‘BBB’ changes, and pv3 will receive callbacks for all changes to ‘CCC’. Note that these dbr.DBE_**** constants are ORed together as a bitmask.

## User-supplied Callback functions

This section describes user-defined functions that are called when the value of a PV changes. These callback functions are useful as they allow you to be notified of changes without having to continually ask for a PVs current value. Much of this information is similar to that in User-supplied Callback functions for the `ca` module, though there are some important enhancements to callbacks on PV objects.

You can define more than one callback function per PV to be run on value changes. These functions can be specified when creating a PV, with the callback argument which can take either a single callback function or a list or tuple of callback functions. After a PV has been created, you can add callback functions with `add_callback()`, remove them with `remove_callback()`, and explicitly run them with `run_callback()`. Each callback has an internal unique index (a small integer number) that can be used for specifying which one to add, remove, and run.

When defining a callback function to be run on changes to a PV, it is important to know two things:

> 1. how your function will be called.

> 2. what is permissible to do inside your callback function.

Callback functions will be called with several keyword arguments. You should be prepared to have them passed to your function, and should always include **kw to catch all arguments. Your callback will be sent the following keyword parameters:

> - pvname: the name of the pv

> - value: the latest value

> - char_value: string representation of value

> - count: the number of data elements

> - ftype: the numerical CA type indicating the data type

> - type: the python type for the data

> - status: the status of the PV (0 for OK)

> - precision: number of decimal places of precision for floating point values

> - units: string for PV units

> - severity: PV severity

> - timestamp: timestamp from CA server.

> - read_access: read access (`True`/`False`)

> - write_access: write access (`True`/`False`)

> - access: string description of read- and write-access

> - host: host machine and CA port serving PV

> - enum_strs: the list of enumeration strings

> - upper_disp_limit: upper display limit

> - lower_disp_limit: lower display limit

> - upper_alarm_limit: upper alarm limit

> - lower_alarm_limit: lower alarm limit

> - upper_warning_limit: upper warning limit

> - lower_warning_limit: lower warning limit

> - upper_ctrl_limit: upper control limit

> - lower_ctrl_limit: lower control limit

> - chid: integer channel ID

> - cb_info: (index, self) tuple containing callback ID

>     and the PV object

Some of these may not be directly applicable to all PV data types, and some values may be `None` if the control parameters have not yet been fetched with `get_ctrlvars()`.

It is important to keep in mind that the callback function will be run inside a CA function, and cannot reliably make any other CA calls. It is helpful to think “this all happens inside of a `pend_event()` call”, and in an epics thread that may or may not be the main thread of your program. It is advisable to keep the callback functions short and not resource-intensive. Consider strategies which use the callback only to record that a change has occurred and then act on that change later – perhaps in a separate thread, perhaps after `pend_event()` has completed.

The cb_info parameter supplied to the callback needs special attention, as it is the only non-Epics information passed. The cb_info parameter will be a tuple containing (`index`, `self`) where `index` is the key for the `callbacks` dictionary for the PV and `self` is PV object. A principle use of this tuple is to remove the current callback if an error happens, as for example in GUI code if the widget that the callback is meant to update disappears.

## User-supplied Connection Callback functions

A connection callback is a user-defined function that is called when the connection status of a PV changes – that is, when a PV initially connects, disconnects or reconnects due to the process serving the PV going away, or loss of network connection. A connection callback can be specified when a PV is created, or can be added by appending to the `connection_callbacks` list. If there is more than one connection callback defined, they will all be run when the connection state changes.

A connection callback should be prepared to receive the following keyword arguments:

> - pvname: the name of the pv

> - conn: the connection status

where conn will be either `True` or ``False`, specifying whether the PV is now connected. A simple example is given below.

## User-supplied Access Rights Callback functions

An access rights callback is a user-defined function that is called when the access rights - read/write permissions - of a PV undergo changes. The callback will be invoked upon successful initialization and at all events that change a PV’s access rights, including disconnection and reconnection events. An access rights callback can be specified when a PV is created, or can be added by appending to the `access_callbacks` list of the PV object. If there are multiple access rights callbacks defined for a PV, they will all be run on access rights events.

## Put with wait, put callbacks, and put_complete

Some EPICS records take a significant amount of time to fully process, and sometimes you want to wait until the processing completes before going on. There are a few ways to accomplish this. First, one can simply wait until the processing is done:

    import epics
    p = epics.PV('XXX')
    p.put(1.0, wait=True)
    print('Done')

This will hang until the processing of the PV completes (motor moving, etc) before printing ‘Done’. You can also specify a maximum time to wait – a timeout (in seconds):

    p.put(1.0, wait=True, timeout=30)

which will wait up to 30 seconds. For the pedantic, this timeout should not be used as an accurate clock – the actual wait time may be slightly longer.

A second method is to use the ‘use_complete’ option and watch for the `put_complete` attribute to become `True` after a `put()`. This is somewhat more flexible than using wait=True as above, because you can more carefully control how often you look for a `put()` to complete, and what to do in the interim. A simple example would be:

    p.put(1.0, use_complete=True)
    waiting = True
    while waiting:
        time.sleep(0.001)
        waiting = not p.put_complete

An additional advantage of this approach is that you can easily wait for multiple PVs to complete with python’s built-in all function, as with:

    pvgroup = (epics.PV('XXX'), epics.PV('YYY'), epics.PV('ZZZ'))
    newvals = (1.0, 2.0,  3.0)
    for pv, val in zip(pvgroup, newvals):
        pv.put(val, use_complete=True)

    waiting = True
    while waiting:
        time.sleep(0.001)
        waiting = not all([pv.put_complete for pv in pvgroup])
    print('All puts are done!')

For maximum flexibility, one can all define a put callback, a function to be run when the `put()` has completed. This function requires a pvname keyword argument, but will receive no others, unless you pass in data with the callback_data argument (which should be dict-like) to `put()`. A simple example would be:

    pv = epics.PV('XXX')
    def onPutComplete(pvname=None, **kws):
        print(f'Put done for {pvname}')

    pv.put(1.0, callback=onPutComplete)

## The `get_pv()` function and `_PVcache_` cache of PVs

As mentioned in the previous chapter, a cache of PVs is maintained for each process using pyepics. When using `epics.caget()`, `epics.caput()` and so forth, or when creating a `PV` directly, the corresponding PV is kept in a global cache, held in `pv._PVcache_`.

The function `get_pv()` will retrieve the named PV from this cache, or create a new `PV` if one is not found. In long-running or complex processes, it is not unusual to access a particular PV many times, perhaps calling a function that creates a PV but only keeping that PV object for the life of the function. Using `get_pv()` instead of creating a `PV` can improve performance (the PV is already connected) and is highly recommended.

pv.get_pv(pvname[, form='time'[, connect=False[, timeout=5[, context=None[, **kws]]]]])

  retrieves a PV from `_PVcache` or creates and returns a new PV.

  Parameters:

    - pvname – name of Epics Process Variable

    - form (string, one of ('native','ctrl', or 'time')) – which epics data type to use: the ‘native’ , or the ‘ctrl’ (Control) or ‘time’ variant.

    - connect (`True`/`False`) – whether to wait for the PV to connect.

    - timeout (float or `None`) – maximum time to wait (in seconds) for value before returning None.

    - context (integer or `None` (default)) – integer threading context.

  Additional keywords are passed directly to `PV`.

pv._PVcache_

  A cache of `PV` objects for the process.

## Examples

Some simple examples using PVs follow.

### Basic Use

The simplest approach is to simply create a PV and use its `value` attribute:

    >>> from epics import PV
    >>> p1 = PV('xxx.VAL')
    >>> print(p1.value)
    1.00
    >>> p1.value = 2.00

The print p1.value line automatically fetches the current PV value. The p1.value = 2.00 line does a `put()` to set the value, causing any necessary processing over the network.

The above example is equivalent to

    >>> from epics import PV
    >>> p1 = PV('xxx.VAL')
    >>> print(p1.get())
    1.00
    >>> p1.put(value = 2.00)

To get a string representation of the value, you can use either

    >>> print(p1.get(as_string=True))
    '1.000'

or, equivalently

    >>> print(p1.char_value)
    '1.000'

### Requests including Metadata

It is also possible to get the metadata associated with a single Channel Access request using `get_with_metadata()`:

    >>> from epics import PV
    >>> p1 = PV('xxx.VAL', form='time')

    >>> print(p1.get())
    1.00

    >>> p1.get_with_metadata()
    {'status': 0,
     'severity': 0,
     'timestamp': 1543429156.811018,
     'posixseconds': 1543429156.0,
     'nanoseconds': 811018603,
     'value': 1.0}

    >>> print(p1.get_with_metadata(form='ctrl'))
    {'upper_disp_limit': 100.0,
     'lower_disp_limit': -100.0,
     'upper_alarm_limit': 0.0,
     'upper_warning_limit': 0.0,
     'lower_warning_limit': 0.0,
     'lower_alarm_limit': 0.0,
     'upper_ctrl_limit': 100.0,
     'lower_ctrl_limit': -100.0,
     'precision': 3,
     'units': 'deg',
     'status': 0,
     'severity': 0,
     'value': 1.0}

### Example of using info and more properties examples

A PV has many attributes. This can be seen from its info paragraph:

    >>> import epics
    >>> p = epics.get_pv('13IDA:m3')
    >>> print(p.info)
    == 13IDA:m3  (native_double) ==
       value      = 0.2
       char_value = '0.200'
       count      = 1
       type       = double
       units      = mm
       precision  = 3
       host       = ioc13ida.cars.aps.anl.gov:5064
       access     = read/write
       status     = 0
       severity   = 0
       timestamp  = 1274809682.967 (2010-05-25 12:48:02.967364)
       upper_ctrl_limit    = 5.49393415451
       lower_ctrl_limit    = -14.5060658455
       upper_disp_limit    = 5.49393415451
       lower_disp_limit    = -14.5060658455
       upper_alarm_limit   = 0.0
       lower_alarm_limit   = 0.0
       upper_warning_limit = 0.0
       lower_warning_limit = 0.0
       PV is internally monitored, with 0 user-defined callbacks:
    =============================

The individual attributes can also be accessed as below. Many of these (the control attributes, see Table of Control Attributes) will not be filled in until either the `info` attribute is accessed or until `get_ctrlvars()` is called.

    >>>  print(p.type)
    double
    >>> print(p.units, p.precision, p.lower_disp_limit)
    mm 3 -14.5060658455

### Getting a string value

It is not uncommon to want a string representation of a PVs value, for example to show in a display window or to write to some report. For string PVs and integer PVs, this is a simple task. For floating point values, there is ambiguity how many significant digits to show. EPICS PVs all have a `precision` field. which sets how many digits after the decimal place should be described. In addition, for ENUM PVs, it would be desire able to get at the name of the ENUM state, not just its integer value.

To get the string representation of a PVs value, use either the `char_value` attribute or the as_string=True argument to `get()`

### Example of `put()`

To put a new value to a variable, either of these two approaches can be used:

    >>> import epics
    >>> p = epics.PV('XXX')
    >>> p.put(1.0)

Or (equivalently):

    >>> import epics
    >>> p = epics.PV('XXX')
    >>> p.value = 1.0

The `value` attribute is the only attribute that can be set.

### Example of simple callback

It is often useful to get a notification of when a PV changes. In general, it would be inconvenient (and possibly inefficient) to have to continually ask if a PVs value has changed. Instead, it is better to set a callback function: a function to be run when the value has changed.

A simple example of this would be:

    import epics
    import time
    def onChanges(pvname=None, value=None, char_value=None, **kw):
        print('PV Changed! ', pvname, char_value, time.ctime())

    mypv = epics.get_pv('PyTest:ao1.VAL', callback=onChanges)

    print('Now wait for changes')
    expire_time = time.time() + 60.
    while time.time() < expire_time:
        time.sleep(0.01)
    print('Done.')

This first defines a callback function called onChanges() and then simply waits for changes to happen. Note that the callback function should take keyword arguments, and generally use **kw to catch all arguments. See User-supplied Callback functions for more details.

### Example of connection callback

A connection callback:

    import epics
    import time

    def onConnectionChange(pvname=None, conn= None, **kws):
        print(f'PV connection status changed: {pvname} {conn}')

    def onValueChange(pvname=None, value=None, host=None, **kws):
        print(f'PV value changed: {pvname} ({host})  {value}')

    mypv = epics.get_pv('PyTest:ao1.VAL',
                        connection_callback= onConnectionChange,
                        callback= onValueChange)

    mypv.get()

    print('Now wait for changes')
    expire_time = time.time() + 60.
    while time.time() < expire_time:
        time.sleep(0.01)
    print('Done.')

### Example of an access rights callback

Associating an access rights callback with a PV:

    import epics
    import time

    def access_rights_callback(read_access, write_access, pv=None):
        print(f'{pv.pvname}: read={read_access}, write={write_access}')

    mypv = epics.get_pv('PyTest:ao1.VAL', access_callback=access_rights_callback)

    print('Now wait for changes')
    expire_time = time.time() + 60.
    while time.time() < expire_time:
        time.sleep(0.01)
    print('Done.')

### Example of a property callback

Callbacks can be set up to receive events not only when a PVs value changes, but also when certain of the PVs properties such as units or limits change. To get such callbacks, subscribe with auto_monitor set to both Value and Property changes, as with:

    import epics
    import time
    def onChange(pvname, value, units='x', **kws):
        print(f'PV changed: {pvname}, value={value}, units={units}')

    mypc = epics.get_pv('PyTest:ao1.VAL', form='ctrl',
                        auto_monitor=epics.ca.dbr.DBE_VALUE|epics.ca.dbr.DBE_PROPERTY,
                        callback=onChange)

    print('Now wait for changes')
    expire_time = time.time() + 60.
    while time.time() < expire_time:
        time.sleep(0.01)
    print('Done.')

note that in this example form=’ctrl’ is used. If the default form of ‘time’ (or ‘native’) had been used, the callback would be called when the property changed, but the value of that property (or even which property changed) would not be included in the callback arguments.