© 2001 By Default! A Free sample background from Slide 1 The Equipment Access API WG Report 6 th February 2003 V. Baggiolini, F.DiMaio, JJ.Gras, M.Jonker, K.Kostro, with contribution from G. Crockford and N. Trofimov AB/COTC

© 2001 By Default! A Free sample background from Slide 2 The Scope TC13 request: TC13 request: –“A more detailed description of the BI device classes, along with their property names and signature –A specification of the equipment access APIs that will be used to perform command/response and subscription actions to the BI instruments. This API that will be built on top of the device/property model and low-level RDA library has to be provided as Java classes with a description of their methods and semantics (list of arguments). The need for a non-Java API has also been raised at several occasions and a C/C+ proposal should be defined.” TC objectives: TC objectives: –“Clarify AB/CO software architecture choices to stop today’s growing divergence of approaches –Start the prototyping with the BI equipment as soon as possible” Mandate of the equipment access API WG: Mandate of the equipment access API WG: –“Functionality and semantics of the equipment access API (client side) is presented and illustrated through practical examples with the LSS4/TT40 BI systems”

© 2001 By Default! A Free sample background from Slide 3 Outline The Device Access Model The Device Access Model TT40 Instrumentation interface TT40 Instrumentation interface Syntax Syntax Conclusion Conclusion

© 2001 By Default! A Free sample background from Slide 4 Outline The Device Access Model The Device Access Model –Device and Properties –Data Format –Cycle Selector –Filters –Acquisition Stamping –Contracts TT40 Instrumentation interface TT40 Instrumentation interface Syntax Syntax Conclusion Conclusion

© 2001 By Default! A Free sample background from Slide 5 Devices and Properties A device is a named entity within the control system, which corresponds to a physical device (Beam Position Monitor, Power Converter) or to a virtual controls entity (e.g. transfer line) A device is a named entity within the control system, which corresponds to a physical device (Beam Position Monitor, Power Converter) or to a virtual controls entity (e.g. transfer line) The state of a device is interfaced by properties and can be read or modified by the get and set access methods. The state of a device is interfaced by properties and can be read or modified by the get and set access methods. –Synchronous get/set: the caller is waiting for the call to be completed –Asynchronous get/set: caller is notified of the outcome of the call by means of a listener (callback) Property can be monitored (publish/subscribe) Property can be monitored (publish/subscribe) –A cycleSelector or a polling period can be specified –On-change mode: only changed data (server criteria) can be requested.

© 2001 By Default! A Free sample background from Slide 6 Data Format Property values delivered to the client or set by the client have the form of Data objects. Property values delivered to the client or set by the client have the form of Data objects. Data object is a container for one or many DataEntry objects. Data object is a container for one or many DataEntry objects. Each DataEntry has a tag (a string) and a value, which can be a scalar, a string or an array of these. Each DataEntry has a tag (a string) and a value, which can be a scalar, a string or an array of these. Complex properties can be composed from simple values Complex properties can be composed from simple values struct { int field1; struct { float partA; int partB} field2; } tag value type field1int field2.partAfloat field2.partBint

© 2001 By Default! A Free sample background from Slide 7 Cycle Selector A cycle selector specifies an accelerator condition for an I/O operation. A cycle selector specifies an accelerator condition for an I/O operation. Settings that are cycle-dependent (“PPM”) require a cycle selector. Settings that are cycle-dependent (“PPM”) require a cycle selector. Currently specified as a String, to be interpreted by the equipment servers via timing services. Currently specified as a String, to be interpreted by the equipment servers via timing services. PS semantics : telegram.group.line PS semantics : telegram.group.line –CPS.USER.SFTPRO SPS semantics : sequence.cycle.cycle-instance SPS semantics : sequence.cycle.cycle-instance –SPS_production_FT_CNGS.CNGS.2

© 2001 By Default! A Free sample background from Slide 8 Filters The RDA protocol (vs 2) supports an additional parameter (a Data object). It is used for transmitting an optional remote filter for I/O (restricted to get/set for now). The RDA protocol (vs 2) supports an additional parameter (a Data object). It is used for transmitting an optional remote filter for I/O (restricted to get/set for now). A filter typically reduces the content of the data exchanged with the device without changing the state of device. A filter typically reduces the content of the data exchanged with the device without changing the state of device. Examples: Examples: –Selecting a sub-range of an array –Selecting a bunch number (without moving a timing gate!).

© 2001 By Default! A Free sample background from Slide 9 Acquisition Stamping All data sent to the client is accompanied by a timeStamp. The meaning of this timestamp can depend on the device but it usually describes the best approximation of time at which the acquisition was made (or a setting was changed). All data sent to the client is accompanied by a timeStamp. The meaning of this timestamp can depend on the device but it usually describes the best approximation of time at which the acquisition was made (or a setting was changed). In the PS complex, timestamps are replaced by cyclestamps to facilitate the correlation of data belonging to the same cycle. A cycleStamp is the timestamp at begin of the cycle for which the acquisition was made and it uniquely identifies the cycle. In the PS complex, timestamps are replaced by cyclestamps to facilitate the correlation of data belonging to the same cycle. A cycleStamp is the timestamp at begin of the cycle for which the acquisition was made and it uniquely identifies the cycle. Timestamps (and cycle stamps) are currently expressed as milliseconds from POSIX origin (Jan 1970) and transmitted as seconds in a double. Timestamps (and cycle stamps) are currently expressed as milliseconds from POSIX origin (Jan 1970) and transmitted as seconds in a double.

© 2001 By Default! A Free sample background from Slide 10 Contracts A contract is the definition of a list of properties that includes their type description and their semantic. A contract is the definition of a list of properties that includes their type description and their semantic. A contract defines a service that can be either generic one (ex: State, Alarm, Settings) or specific one (ex: Beam Position). A contract defines a service that can be either generic one (ex: State, Alarm, Settings) or specific one (ex: Beam Position). The device servers implement contracts (analog to the Java interface concept). The device servers implement contracts (analog to the Java interface concept). Different contract management methods: Different contract management methods: –PS (database) –SPS2001 (XML) –BISCoTO (text files)

© 2001 By Default! A Free sample background from Slide 11 Outline The Device Access Model The Device Access Model TT40 Instrumentation interface TT40 Instrumentation interface –BCT Acquisitions –Device & Property definition –The BCT Acquisition property Syntax Syntax Conclusion Conclusion

© 2001 By Default! A Free sample background from Slide 12 BCT Acquisitions (SPS2001) Acquisition conditions descriptorString superCycleCountInteger timeStampDouble Acquisition / monitor numberOfBunchesInteger totalBeamIntensityFloat bunchIntensityFloat[MAX_BUNCHES] maximumBunchIntensityFloat minimumBunchIntensityFloat bunchSpreadSigmaFloat statusTagLong Shall be standardized

© 2001 By Default! A Free sample background from Slide 13 Device & property definition Device can be either one monitor or the complete instrument in one crate Device can be either one monitor or the complete instrument in one crate Acquisition properties can return either the complete acquisition data or one component (ex: bunch intensity). Acquisition properties can return either the complete acquisition data or one component (ex: bunch intensity). Acquisition conditions must always be included into the returned data object. Acquisition conditions must always be included into the returned data object.

© 2001 By Default! A Free sample background from Slide 14 Example: BCT Acquisition property Data object for the Acquisition property tag value type cycleDescriptorString cycleStampDouble timeStampDouble numberOfMonitorsInteger numberOfBunchInteger maximumBunchIntensityFloat[nbOfMon] bunchIntensity Float[NbOfBunch * nbOfMon ] minimumBunchIntensity Float[nbOfMon] bunchSpreadSigmaFloat[nbOfMon] statusTagLong[nbOfMon] 1 device / crate & 1 property returning all acquisition data Proposed Standard

© 2001 By Default! A Free sample background from Slide 15 (suite) For reading only a component of the acquisition data: Either an additional dedicated property Either an additional dedicated property –Ex: “bunchIntensity” Or structured property names: property[.field] handled by the server. Or structured property names: property[.field] handled by the server. –Ex: “Acquisition.bunchIntensity” Feasible for BISCoTO/CMW servers

© 2001 By Default! A Free sample background from Slide 16 Outline The Device Access Model The Device Access Model TT40 Instrumentation interface TT40 Instrumentation interface Syntax Syntax –Java APIs –RDA/CMW Examples –Specific API Conclusion Conclusion

© 2001 By Default! A Free sample background from Slide 17 Current Client Java APIs RDA package Narrow Narrow Very flexible Very flexible Less User Friendly Less User Friendly Based on CORBA Based on CORBA Supported by CO/FC Supported by CO/FC CMW package Narrow Narrow Less flexible (more “guided”) Less flexible (more “guided”) More User Friendly More User Friendly Now on RDA; “pluggable” to other layers (e.g. JMS) Now on RDA; “pluggable” to other layers (e.g. JMS) Supported by CO/AP Supported by CO/AP RDA Client CMW Client

© 2001 By Default! A Free sample background from Slide 18 Java APIs RDA CMW Cesar BISCoTO ASC SPS-2001 Direct CMW Client ASC Beans

© 2001 By Default! A Free sample background from Slide 19 Java API Proposal Merge CMW and RDA to a unique Client Middleware API (integrate a part of CMW into RDA) Merge CMW and RDA to a unique Client Middleware API (integrate a part of CMW into RDA) Done and supported by the FC section Done and supported by the FC section APIs on top with “added value” done and supported by the AP section for OP programs APIs on top with “added value” done and supported by the AP section for OP programs Will suppress redundant work & ambiguity for the users. Will suppress redundant work & ambiguity for the users.

© 2001 By Default! A Free sample background from Slide 20 RDA/C++ Example void printProperty (String deviceName, String propName, String cycleSelector) { // Initialize RDA and obtain the device handle // Initialize RDA and obtain the device handle rdaRDAservice* rda = rdaRDAService::init(); * device = rda->(deviceName); rdaDeviceHandle* device = rda->getDeviceHandle(deviceName); // Read and print the property value // Read and print the property value rdaData* result; try { result = device->get(propName, cycleSelector); cout get(propName, cycleSelector); cout << *result; delete result; } catch(const rdaException& ex) { cerr << ex; } }

© 2001 By Default! A Free sample background from Slide 21 CMW/Java Example // Measurement listener: update a plot with H pos class trajectoryRefresher implements MonitoringListener { public void handleData(MonitoringToken mt, Data value) { // Extract H pos from the Data object // Extract H pos from the Data object Float[] newPos = value.extractFloatArray(“horizontalPosition”); Float[] newPos = value.extractFloatArray(“horizontalPosition”); plot.updateY(newPos); // for example plot.updateY(newPos); // for example} public void handleException(MonitoringToken mt, CmwException ex) { System.err.println("Received exception: " + ex.getMessage()); System.err.println("Received exception: " + ex.getMessage());}…} tag

© 2001 By Default! A Free sample background from Slide 22 BCT Specific API If required, a « wide » (strongly typed) interface can be built on top of the CMW/RDA layer (or any other generic layer). If required, a « wide » (strongly typed) interface can be built on top of the CMW/RDA layer (or any other generic layer).Example: This could be automatically generated from a contract definition This could be automatically generated from a contract definition class BaseAcquisition extends … { private Data data; private Data data; public double getCycleStamp() {…}; public double getCycleStamp() {…};} class BCTAcquisition extends BaseAcquisition { public int getNumberOfMonitors() throws rdaException public int getNumberOfMonitors() throws rdaException{ // RDA code to extract it from the Data object // RDA code to extract it from the Data object return data.extractInt(“numberOfMonitor”); } public float[] getBunchIntensity(int bunchNb) {…} public float[] getBunchIntensity(int bunchNb) {…}}

© 2001 By Default! A Free sample background from Slide 23 BCT Contract Server Client Acquisitions BCT Contract Acq. definition

© 2001 By Default! A Free sample background from Slide 24 Conclusion The Middleware client API provides a very solid base for Java & for C/C++ (Linux, Windows), with a flexible usage but with a stable syntax. The Middleware client API provides a very solid base for Java & for C/C++ (Linux, Windows), with a flexible usage but with a stable syntax. –In operation on the PS complex –BISCoTO devices are interfaced –SL-EQUIP & OPC gateways Wide, extended, user-friendly APIs can be built on top but, not many. Wide, extended, user-friendly APIs can be built on top but, not many. –Each connection requires work & a friendly collaboration. –Please, anticipate maintenance scenario In addition, common methods and tools for specifying the contracts are necessary In addition, common methods and tools for specifying the contracts are necessary –To obtain reliable definition between servers and clients –To allow common generic software –To allow reliable, automatically generated, specific APIs.

© 2001 By Default! A Free sample background from Slide 25 Connecting a TT40/BI device? Provide a BISCoTO/CMW server Code the specific API Record the contracts Produce a validation application Generate the specific API Connect a generic application