Difference between revisions of "V4 CA Client User Interface"

From EPICSWIKI
(how to get property info?)
(TIPC)
 
(17 intermediate revisions by 3 users not shown)
Line 14: Line 14:
Is there anything we can learn from other communication libraries?
Is there anything we can learn from other communication libraries?
* A brief look at [[ZeroC ICE]]
* A brief look at [[ZeroC ICE]]
* TIPC, the Transparent Inter Process Communication protocol (TIPC) started out as a communications layer for building clusters, I think by Ericson, and is now becoming more open and also supported by  the latest WindRiver vxWorks releases.<br>The Buzz:
** allows socket-based applications to communicate easily and efficient
** based on publicly available source code
** A location-transparent addressing scheme
** Efficient, rapid, and reliable interprocess communication within a node and between nodes, using either connection-oriented or connectionless modes of operation
** Rapid notification of changes in topology and the ability to adjust quickly to these changes
== Constraints ==
* Initial implementation will be in C++
* Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
* Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
* API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.


== Skeleton API ==
== Skeleton API ==
Line 28: Line 40:
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)<BR>Used by CA servers to remove their PV from directory
* deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)<BR>Used by CA servers to remove their PV from directory


Note that Ben argues to hide the directory lookup from the CA client user.
There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()".
The implementation could use
* LDAP
* Broadcast (as before)
* your custom implementation<br>as long as it uses the above interface and registers itself as the default.


Note that Ben argues to hide the directory lookup from the CA client us
er.
See separate  [[V4 Name Server]] wiki for the issue of "record" and "PV" information.
See separate  [[V4 Name Server]] wiki for the issue of "record" and "PV" information.


=== Data Access ===
=== Data ===
All the data is accessed via DataAccess, which handles the introspection
The available ''data'' constists of property names, types and values, for example:
of arbitrary data types. It should provide the following convenience
    double    value; // The "value" property of our data
routines in addition to whatever more efficient methods it might have
    string    units; // The "units" property....
(using hash IDs instead property name string etc.):
    time_stamp time;
* list<string> getProperties()<BR>Get a list of all the properties
 
* type_info getType(string property)
The data might contain arrays and structures.
* bool hasWriteAccess(string property)
The user might not want all the properties, and the user might also want to get properties in non-native types (strings for convenience, float instead of double to preserve space, ...).
* string getAsString(string property)
The client has to provide storage, and might allocate this:
    float  value;
    string units;
 
The user interface must provide the following:
* getAllProperties()<BR>Get a list of all the property names and their data type so that the client can make an informed decision for allocating its storage of the data. There might be helper routines to convert between human-usable strings and more efficient numeric identifiers.
* bool hasWriteAccess(string property)<BR>Could also be part of the info return by previous method.
 
This functionality is available without getting any actual data.
To retrieve values, the user asks the client library to place the data into
the client-provided storage.
The ''traverse'' of the "dataAccess" proposal handles this by asking
the user to implement a property catalog that ''reveals'' each storage element.
The end effect is not too different from having the user invoke methods
like these:
* getAsString(string property, string *my_storage)
* getAsDouble(string property, double *my_storage)
* ...many more, one for each available data type.


=== Channel ===
=== Channel ===
Line 47: Line 82:
* getName()<br>Returns the name of the channel.
* getName()<br>Returns the name of the channel.
* addListener(Listener l), removeListener(Listener l)<br>Register for notifications, see below.
* addListener(Listener l), removeListener(Listener l)<br>Register for notifications, see below.
* getProperties()<br>A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.


Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.
Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.
Line 54: Line 90:
Is there a "get all properties" request that reads them on-demand
Is there a "get all properties" request that reads them on-demand
from the CA server?
from the CA server?
Or does the directory hold the list of available properties and their types?  
Or does the directory hold the list of available properties and their types?


=== Channel: Listener ===
=== Channel: Listener ===
Line 63: Line 99:
** DataAccess interface to the data
** DataAccess interface to the data
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
** Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
* disconnected(Channel ch)
* accessRightChange(Channel ch)
* accessRightChange(Channel ch)


Line 74: Line 109:
* bool isConnected()<BR> .. for those who want to poll
* bool isConnected()<BR> .. for those who want to poll
* xxx getServerInfo(), xxx getType()<BR>  .. only valid when isConnected().
* xxx getServerInfo(), xxx getType()<BR>  .. only valid when isConnected().
* setUser(), ...<BR>Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime.
* setUser(), ...<BR>Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.


=== Channel: Writing ===
=== Channel: Writing ===
* write(new value)<BR>Sends the value to the server.
* write(new value)<BR>Sends the value to the server.
* createWriteRequest(new value, receipt {delivery, completion})<BR>Sends the value to the server, invokes Listener when CA server has received the value respectively all the processing triggered by the new value has completed.
* createWriteRequest(new value, receipt {delivery, completion, response})<BR>Sends the value to the server, invokes Listener when CA server has received the value (delivery) or  all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
* scheduleWriteRequest(new value, event)<BR>Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.
* scheduleWriteRequest(new value, event)<BR>Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.


=== Channel: Reading ===
=== Channel: Reading ===
* createSubscription(list<property> what, Event e, Filter f)<BR>Will invoke Listener once data arrives.
* createSubscription(list<string> properties, Event e)<BR>Will invoke Listener once data arrives.
** event is a set of any of the following:
* cancelSubscription(....)<BR>Use properties & event or an ID returned from createSubscription?
*** exceeded absolute value deadband, exceeded percentage change, exceeded logarithmic change
 
*** minimum update period expired
Event is a class that allows the user to select what triggers an update:
*** alarm condition change
* useDefaultValueDeadband()<BR>Default if nothing else is called.
*** some hardware event (like blue beam)
* setValueDeadband(double change)
** filters
* setPercentageDeadband(double percent)
*** override server-side idea of the value deadband, percentage change, log. change, minumum update rate, maximum update rate
* setLogarithmicDeadband(double exponent_of_ten)
*** specify value count<br>setting this to '1' turns the subscription into a single-value 'get'
* setMinimumRate(double seconds)<BR>There will be notifications at at least this rate, even if value didn't change.
* cancelSubscription(Event, Filter)
* setMaximumRate(double vals_per_second)
* useAlarmConditionChange()
* useHardwareEvent(int event_id)<br>Somehow, event_id might be linked to 'Blue Beam'
* setMaxValueCount<br>Setting this to '1' turns the subscription into a single-value 'get'.
 
Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala
"valueDeadband=1.0, maximumRate=20" which is supported by methods
* string toString()
* bood fromString(string event_specification)
 
=== ChannelGroup ===
A channel group synchronizes access to multiple channels.
It listens to all members of the channel group and for example
allows waiting for ''all'' outstanding read or write requests
to return.
 
* add/remove channels<br>By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
* read/write<br>Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?


=== SyncChannel ===
=== SyncChannel ===
A wrapper class around the async. Channel.
A wrapper class around the async. Channel.
Uses a configurable timeout and provides synchronous 'read', 'write'.
Uses a configurable timeout and provides synchronous 'read'.
 
* Inherits from Channel.
* double getTimeout(), void setTimeout(double seconds)
* DataAccess read(list<string> properties)<BR>Synchronous read of current values of properties.
* DataAccess read(string property)<BR>Synchronous read of current value of one property.


=== Container ===
=== Container ===
Line 105: Line 162:
* detach()
* detach()
* implements the DataAccess interface to allow access to the data.
* implements the DataAccess interface to allow access to the data.
Also see [[V4 Data Store]]


== caget 101 ==
== caget 101 ==
Line 112: Line 171:
  DataAccess da = channel.read("value");
  DataAccess da = channel.read("value");
  cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";
  cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";
  channel.disconnect();
 
We can imagine an even simpler example:
 
cout << "Value of fred:" << Epics::get("fred") << "\n";
 
This implies lots of work under the hood, with reasonable defaults.
 
== camonitor 101 ==
This is the goal for a 'camonitor':
 
class MyMonitor : public Channel::Listener
{
public:
  newData(Channel ch, DataAccess data, Event why)
  {
        cout << channel.getName() << " = " << da.getAsString("value") << "\n";
  }
};
...
Channel channel("fred");
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
  channel.createSubscription(properties, e);

Latest revision as of 19:13, 16 July 2005

Channel Access Client User Interface

Under V4, a ProcessVariable would no longer be limited to the current properties 'value', 'units', ... but allow the users to create CA servers and clients that understand new properties.

The low-level V4 CA client API is likely to be rather complex because it now needs to handle arbitrary property catalogs.

  • There still needs to be an easy to use high-level API, not much more complex than the existing one.
  • There needs to be access to CA from languages like Matlab in a way that's as easy as
pv = caopen('fred');
value = caget(pv);

Food for thought

Is there anything we can learn from other communication libraries?

  • A brief look at ZeroC ICE
  • TIPC, the Transparent Inter Process Communication protocol (TIPC) started out as a communications layer for building clusters, I think by Ericson, and is now becoming more open and also supported by the latest WindRiver vxWorks releases.
    The Buzz:
    • allows socket-based applications to communicate easily and efficient
    • based on publicly available source code
    • A location-transparent addressing scheme
    • Efficient, rapid, and reliable interprocess communication within a node and between nodes, using either connection-oriented or connectionless modes of operation
    • Rapid notification of changes in topology and the ability to adjust quickly to these changes

Constraints

  • Initial implementation will be in C++
  • Should very easily translate into Java, just like e.g. some XML APIs use the exact same classes and methods in C++ and Java. Ideally, Java and C++ version will be available from the start.
  • Ideally, the C++ headers would be simple enough to be parsed by SWIG and hence perl/tcl/python/... glue code could be auto-generated via SWIG
  • API is of course specific to EPICS CA, but ideally it'll also be usable as an interface to other protocols, so that EPICS Office can use an API that is only a slight extension of the CA client user API.

Skeleton API

What follows is in the form of pseudo classes and associated methods that a CA client API should provide.

Directory

The directory is used to discover available channels and map them to the CA Server address and port.

  • Directory(string URL-type-server-address = "")
    Constructor; uses site-specific default server or specific one. The 'URL' might contain a user & password, which decides if this name server connection is read-only (for OPI clients) or if writes are allowed (for IOCs that add PVs to the name server).
  • getChannelInfo(string PV_or_pattern)
    Returns list of
    • CA server - IP & port of server that has the PV
    • quality - is this the IOC, a gateway, backup/primary
  • addChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)
    Used by CA servers to register their PV in directory
  • deleteChannelInfo(string PV, CASInfo addr_and_port, CASType primary_or_backup_or...)
    Used by CA servers to remove their PV from directory

There is a default directory, available via something like "EPICSDefaults::getDirectory()" and "...setDirectory()". The implementation could use

  • LDAP
  • Broadcast (as before)
  • your custom implementation
    as long as it uses the above interface and registers itself as the default.

Note that Ben argues to hide the directory lookup from the CA client us er. See separate V4 Name Server wiki for the issue of "record" and "PV" information.

Data

The available data constists of property names, types and values, for example:

    double     value; // The "value" property of our data
    string     units; // The "units" property....
    time_stamp time;
 

The data might contain arrays and structures. The user might not want all the properties, and the user might also want to get properties in non-native types (strings for convenience, float instead of double to preserve space, ...). The client has to provide storage, and might allocate this:

    float  value;
    string units;

The user interface must provide the following:

  • getAllProperties()
    Get a list of all the property names and their data type so that the client can make an informed decision for allocating its storage of the data. There might be helper routines to convert between human-usable strings and more efficient numeric identifiers.
  • bool hasWriteAccess(string property)
    Could also be part of the info return by previous method.

This functionality is available without getting any actual data. To retrieve values, the user asks the client library to place the data into the client-provided storage. The traverse of the "dataAccess" proposal handles this by asking the user to implement a property catalog that reveals each storage element. The end effect is not too different from having the user invoke methods like these:

  • getAsString(string property, string *my_storage)
  • getAsDouble(string property, double *my_storage)
  • ...many more, one for each available data type.

Channel

  • Channel(string name, Directory dir = default)
    Constructor. Channel has to have a name. Uses the 'best' channel from the default directory or from a given directory.
  • Channel(string name, CASInfo)
    ... in case you want a specific server after querying the directory yourself or not using a directory at all.
  • getName()
    Returns the name of the channel.
  • addListener(Listener l), removeListener(Listener l)
    Register for notifications, see below.
  • getProperties()
    A read or subscription will return a dataAccess interface to the retrieved data. That might exclude properties that this client cannot access. It will include the data, which might be huge. This separate call will only get property information, no data, for all properties, including read/write access information. The result could be in the form of dataAccess, except all access to actual data yields empty results, only the property-info related part of dataAccess is functional.

Note that Ben suggests that the CA client library should select the CA server automatically by querying a server or via broadcasts; it should also pick amongst competing PVs of the same name without user interaction.

Note also that in order to read or write, one needs to know what properties to access. Does the channel magically provide a list of all properties? Is there a "get all properties" request that reads them on-demand from the CA server? Or does the directory hold the list of available properties and their types?

Channel: Listener

The Channel::Listener interface is invoked in response to the many asynchronous methods of the Channel.

  • writeComplete(Channel ch)
    • Channel that send this notification
  • newData(Channel ch, DataAccess data, Event why)
    • DataAccess interface to the data
    • Reason for the update: Value deadband exceeded, minimum period expired, event 'blue beam', ...
  • accessRightChange(Channel ch)

Alternatively, these could be separate interfaces for a writeListener, dataListener, stateListener.

Channel: State

In contrast to the V3 API, the user doesn't 'connect'. The first data notification implies that we're connected.

  • bool isConnected()
    .. for those who want to poll
  • xxx getServerInfo(), xxx getType()
    .. only valid when isConnected().
  • setUser(), ...
    Sets/changes the 'user' that determines the access rights, allowing OPI tools to adjust this per-channel at runtime. To avoid security issues, setUser will probably send a public key and not a user name and password.

Channel: Writing

  • write(new value)
    Sends the value to the server.
  • createWriteRequest(new value, receipt {delivery, completion, response})
    Sends the value to the server, invokes Listener when CA server has received the value (delivery) or all the processing triggered by the new value has completed (completion). In addition, some records might support command/response, in which case one can write a command and wait for a response callback which looks just like the result of a read request.
  • scheduleWriteRequest(new value, event)
    Sends the value to the server, which will perform the write when the given event fires. Invokes Listener when CA server has performed the write.

Channel: Reading

  • createSubscription(list<string> properties, Event e)
    Will invoke Listener once data arrives.
  • cancelSubscription(....)
    Use properties & event or an ID returned from createSubscription?

Event is a class that allows the user to select what triggers an update:

  • useDefaultValueDeadband()
    Default if nothing else is called.
  • setValueDeadband(double change)
  • setPercentageDeadband(double percent)
  • setLogarithmicDeadband(double exponent_of_ten)
  • setMinimumRate(double seconds)
    There will be notifications at at least this rate, even if value didn't change.
  • setMaximumRate(double vals_per_second)
  • useAlarmConditionChange()
  • useHardwareEvent(int event_id)
    Somehow, event_id might be linked to 'Blue Beam'
  • setMaxValueCount
    Setting this to '1' turns the subscription into a single-value 'get'.

Unclear how to present the Event to a user. For example, how would a 'camonitor' tool allow the user to select the events? Via 20 command-line switches, or should there be a syntax ala "valueDeadband=1.0, maximumRate=20" which is supported by methods

  • string toString()
  • bood fromString(string event_specification)

ChannelGroup

A channel group synchronizes access to multiple channels. It listens to all members of the channel group and for example allows waiting for all outstanding read or write requests to return.

  • add/remove channels
    By name? Already existing Channel? Add channels that match a pattern, or go via the directory?
  • read/write
    Has to handle reading/writing the same properties from all channels in group. Also channel-specific list of properties?

SyncChannel

A wrapper class around the async. Channel. Uses a configurable timeout and provides synchronous 'read'.

  • Inherits from Channel.
  • double getTimeout(), void setTimeout(double seconds)
  • DataAccess read(list<string> properties)
    Synchronous read of current values of properties.
  • DataAccess read(string property)
    Synchronous read of current value of one property.

Container

The Channel does not store any data. When attaching a container to a channel, the container will subscribe to the channel and keep a copy of all data, so one can always ask the container for the current values.

  • attach(channel)
  • detach()
  • implements the DataAccess interface to allow access to the data.

Also see V4 Data Store

caget 101

This is how a simple 'caget' could be written:

SyncChannel channel("fred"); 
DataAccess da = channel.read("value");
cout << "Value of " << channel.getName() << " : " << da.getAsString("value") << "\n";

We can imagine an even simpler example:

cout << "Value of fred:" << Epics::get("fred") << "\n";

This implies lots of work under the hood, with reasonable defaults.

camonitor 101

This is the goal for a 'camonitor':

class MyMonitor : public Channel::Listener
{
public:
  newData(Channel ch, DataAccess data, Event why)
  {
       cout << channel.getName() << " = " << da.getAsString("value") << "\n";
  }
};
...
Channel channel("fred"); 
list<string> properties;
properties.push_back("value");
Event e;
e. setMaximumRate(10.0);
channel.createSubscription(properties, e);