TANGO training How to develop a TANGO device

TANGO training How to develop a TANGO device

Preamble n Ambition – Approaching different steps of a device development – Handling the tools n Collective approach n Individual approach – Operating concepts of session I – A C++ example – Read the documentation ! • Tutorial C++ & Java • Many implementation details

The example n Servers… – device Beam. Image • Beam image (made in the plan of 1 screen) • Supposed to be linked to a camera (with on/off ctrl ) • Params : size (pixels) , scaling (mm/pixel) – device Beam. Dim • • n Profiles and size of beam Logical device (SC service) Analysis of the image produced by Beam. Image Params : image source (device) The client(s)… – Matlab and/or Igor Pro and/or Device. Tree

E 1 : Definition of interfaces n Preliminary essential step – Led by the clients’ need – Functionalities and/or datas to «export» ? n Contract with the clients – Attractive choice – Strong link with non generic clients n Elementary choices – Commands, Attributes, Ownerships – Command or Attribute ? • command ~ action • attribute ~ physical size «monitorable»

E 1 : Beam. Image : interface – – – Commands void Set. Image. Size(long) long Get. Image. Size(void) void Set. Image. Scaling(double) double Get. Image. Scaling(void) void Switch. On (void) void Switch. Off (void) size pixels (size * scaling) mm n 6 (size * scaling) mm

E 1 : Beam. Image : interface n 3 Attributes size pixels (size * scaling) mm – size • WRITE, SCALAR, LONG – scaling • READ_WRITE, SCALAR, DOUBLE – bimage • READ, IMAGE, LONG (size * scaling) mm

E 1 : Beam. Image : interface n 2 States – ON • Camera ON • All commands authorized except Switch. On • Reading image authorized – OFF • Camera OFF • No authorized command except Switch. On • Reading image forbidden – TANGO • State management -> command execution • No state management -> reading/writing attribute

E 1 : Beam. Dim : interface n 2 Commands • string Get. Image. Source(void) • void Set. Image. Source(string)

E 1 : Beam. Dim : interface n 4 Attributes – x_profil & y_profil • READ, SPECTRUM, LONG – x_dim & y_dim • READ, SCALAR, DOUBLE x_profil x_dim

E 2 : Code generation n POGO – The Program Obviously used to Generate Tango Objects – Java Application • Win 32, Linux, Sun-Solaris – Code generator • C++ or Java – Devices skeleton • Commands, Attributes, Ownerships, States – To launch POGO under Windows… • %SOLEIL_ROOT%tangowin 32scriptstart-pogo. bat

E 2 : POGO : Prog. Language

E 2 : POGO : New Project

E 2 : POGO : New Project Classe du device

E 2 : POGO : New Project

E 2 : POGO : States class Beam. Image interface : états -ON : Camera on -OFF : Camera off

E 2 : POGO : Commands class Beam. Image interface : commands Tango: : DEV_VOID Set. Image. Size(Tango: : DEV_LONG) - allowed for states: ON Tango: : DEV_LONG Get. Image. Size(Tango: : DEV_VOID) - allowed for states: ON Tango: : DEV_VOID Set. Image. Scaling(Tango: : DEV_DOUBLE) - allowed for states: ON, OFF Tango: : DEV_DOUBLE Get. Image. Scaling(Tango: : DEV_VOID) - allowed for states: ON, OFF Tango: : DEV_VOID Switch. On(Tango: : DEV_VOID) – allowed for states: OFF Tango: : DEV_VOID Switch. Off(Tango: : DEV_VOID) – allowed for states: ON

E 2 : POGO : Attributes class Beam. Image interface : attributes –size • WRITE, SCALAR, LONG • Val_Min = 100, Val_Max = 500, Unit = pixels • Write allowed for states : ON –scaling • READ_WRITE, SCALAR, DOUBLE • Val_Min = 0. 001, Val_Max = 10, Unit = mm/pixel • Read/Write allowed for states : ON, OFF –image • READ, IMAGE, LONG • Read allowed for states : ON

E 2 : POGO : Code generation

E 2 : POGO : Doc generation

E 3 : Compilation n Creating the working environment – Positioning the variables of environnement • %SOLEIL_ROOT%envwin 32env. SOLEIL. bat • executing this script in a console – Copying and modifying the Makefile • %SOLEIL_ROOT%envwin 32Makefile. VC • copying to the directory of the device • editing : device_server = Beam. Image n Compiler – nmake –f Make. File. VC all – nmake –f Make. File. VC clean

E 3 : Compilation n Where is the result of the compilation ? – Intermediate files • C: TEMP{USER NAME}{DEVICE NAME} – Executable • C: Device. Serversds_{DEVICE NAME}. exe

E 4 : Execution n Syntax – {EXEC NAME} {INSTANCE NAME} [-v{VERBOSE LEVEL}] • {EXEC NAME} = name of the binary • {INSTANCE NAME} = name of the device instance – C: Device. Serversds_Beam. Image 1 –v 4

E 4 : Execution n Syntax – {EXEC NAME} {INSTANCE NAME} [-v {VERBOSE LEVEL}] • {EXEC NAME} = name of the binary • {INSTANCE NAME} = instance name of the device – C: ds_Beam. Image 1 –v 4 n Oups! – The device server ds_Beam. Image/1 is not defined in database. Exiting! – Save the server in the TANGO database • Jive : %SOLEIL_ROOT%win 32scriptstart-jive. bat – Option –nodb (cf. TANGO programmer’s manual)

E 4 : Execution (recording)

E 4 : Execution (recording)

E 4 : Execution n Second attempt – {EXEC NAME} {INSTANCE NAME} [-v {VERBOSE LEVEL}] • {EXEC NAME} = name of the binary • {INSTANCE NAME} = instance name of the device – C: ds_Beam. Image 1 –v 4

E 4 : Execution n Second attempt – {EXEC NAME} {INSTANCE NAME} [-v {VERBOSE LEVEL}] • {EXEC NAME} = name of the binary • {INSTANCE NAME} = instance name of the device – C: ds_Beam. Image 1 –v 4 n This time … – Ready to accept request – Device waiting for external requests – Integrated into the control system • Appreciate what is done for you !

E 4 : Execution n Test – Generic client : Device. Tree, Igor Pro, Matlab n At this stage … – The device runs but does nothing – The interface remains to be implemented • Do what you declare doing !

E 5 : Implementation n What is POGO ? – Basic code of the device : 6 files • main. cpp – initialisation of the process and activation of the device • Class. Factory. cpp – Internal cooking of TANGO (extra load via linker) Free ! • {Beam. Image}Class. h • {Beam. Image}Class. cpp – header and impl. of the class (in the TANGO sense) of Beam. Image devices. – Implement a « Beam. Image factory » – Instanciation of devices , commands, attributes – States management (for the execution of commands only!) – Reading/writing of «class properties» in the TANGO database Not expensive ! • {Beam. Image}. h • {Beam. Image}. cpp – «Implementation class» of Beam. Image devices – Implementation of the interface : role of the developer !

E 4 : Implementation n What is POGO generating (continuation) ? – The « glue» allowing to integrate the device to SC – An «empty» implementation of the device ! n Developer role – Implementing the specific code (acquisition, calculation, simulation, …) – Linking this code to the TANGO interface (generated by POGO)

E 5 : Implementation S C SOLEIL Control system (applications network) S C S C client application. S Server application. POGO TANGO Developer Application logic Material Supplier (driver, lib, …)

E 5 : Implementation n To – – do … Implementing the commands Implementing reading/writing of attributes Managing the states Taking into account the ownerships (stored in the database) n Where to intervene? – {Device. Class. Name}. h et {Device. Class. Name}. cpp – Here : Beam. Image. h et Beam. Image. cpp

E 5 : Implementation : command n Execution command : – Tango: : DEV_LONG Set. Image. Size(Tango: : DEV_LONG) Beam. Image (CORBA Obj. ) Beam. Image. Class (Device Class) Set. Image. Size (Command) Beam. Image (Device Impl. ) command_inout CORBA: : Any command_handler CORBA: : Any always_executed_hook is_allowed execute CORBA: : Any set_image_size Tango: : Dev. Long

E 5 : Implementation : command Beam. Image. h /** * Turns the camera on * @exception Dev. Failed */ void switch_on(); Beam. Image. cpp //------------------------------// method: Beam. Image: : switch_on // description: method to execute "Switch. On" // Turns the camera on //------------------------------void Beam. Image: : switch_on() { cout 2 << "Beam. Image: : switch_on(): entering. . . !" << endl; // Add your own code to control device here }

E 5 : Implementation : command Beam. Image. h /** * Turns the camera on * @exception Dev. Failed */ void switch_on(); Beam. Image. cpp //------------------------------// method: Beam. Image: : switch_on // description: method to execute "Switch. On" // Turns the camera on //------------------------------void Beam. Image: : switch_on() { cout 2 << "Beam. Image: : switch_on(): entering. . . !" << endl; // Add your own code to control device here set_state(Tango: : ON); set_status(‘Device up and ready (camera is on)’); } The TANGO command «Switch. On» is implemented !

E 5 : Implementation : command n Main difficulties – Client/server exchange • Device client of a device (cf. Beam. Dim) – Rules of management of the memory in C++ • Allocation/De-allocation (Ownership) – CORBA (for certain types) • Strings, Sequences, Any (insertion/extraction) – Section 7. 2 of the Tango programmer’s guide • Read this or die ! – An example (a model) • Device Tango. Test • An ex. of command for each TANGO type

E 5 : Implementation : command n Management of – C++ Exceptions errors • spread towards the client (CORBA) – Generic exception • Tango: Dev. Failed • Reason, Description, Origin, Severity – Other exceptions (more semantic) • Connection. Failed, Communication. Failed, … – Section 7. 2. 4 of the programmer’s guide

E 5 : Implementation : command n Management of errors (example) // Allocate image buffer image_buffer = new Tango: : Dev. Long[new_size]; // Check allocation if (image_buffer == 0) { Tango. Sys_OMem. Stream o; o << "Failed to allocate beam image buffer" << ends; LOG_ERROR((o. str())); Tango: : Except: : throw_exception( (const char *)"Out of memory error", o. str(), (const char *)"Beam. Image: : set_image_size"); }

E 5 : Implementation : command n Management of errors (example) Tango: : Device. Proxy *isource = … try { Tango: : Device. Data dd; dd = isource->command_inout(“Get. Image. Scaling”); } cacth (Tango: : Dev. Failed& ex) { Tango. Sys_OMem. Stream o; o << "Failed to execute Get. Image. Scaling" << ends; LOG_ERROR((o. str())); Tango: : Except: : re_throw_exception( ex, (const char *)"Tango command failed", o. str(), (const char *)"Beam. Dim: : read_attr_hardware"); }

E 5 : Implementation : command

E 5 : Implementation : attributes n Tricks to know… – The developer «handles» data associated to the attribute, not the attribute itself ! – Variables member of the implementation class with the type of the attribute (and not instances of the Tango class : Attribute) – For a READ attribute, the associated variable member represents the current value of the attribute (i. e. last value read on the hardware) – For a WRITE attribute, it represents the value of the instruction (i. e. value to «write» on the hardware) – Current implementation of TANGO • item being discussed • re-implementation considered

E 5 : Implementation : attributes n READ attribute – – 1 variable member of the implementation class name : attr_{ATTR NAME}_read type : pointer on the attribute type Ex : image attribute of a Beam. Image device • Beam. Image. h (header of the Beam. Image class ) – POGO code : Tango: : Dev. Long *attr_image_read; • Beam. Image. cpp (impl. de la classe Beam. Image) – POGO code : Nothing ! – Data associated to the attribute must be instanced – attr_image_read = new Tango: : Dev. Long[size*size]; – Beware of memory leaks (init_device vs delete_device) !

E 5 : Implementation : attributes n Reading mecanism Beam. Image (Device Impl. ) Beam. Image (CORBA Obj. ) read_attributes(Attr 1, Attr 2) always_executed_hook read_attr_hardware (Attr 1, Attr 2) read_attr (Attr 1) read_attr (Attr 2)

E 5 : Implementation : attributes n Reading mecanism – About read_attribut_hardware… • 1 call for the n attributes to read • object : reading the hardware only once • update of variable members of the type <…_read> – About read_attr… • 1 call per attribute to read • object : affected a value to the attribute • associating the attribute and the variable member which represents it – attr. set_value(attr_image_read, size)

E 5 : Implementation : attributes n WRITE attribute – 1 variable member of the implementation class – name : attr_{ATTR NAME}_write • POGO 1. 33 imperfection : also generates attr_{ATTR NAME}_read (do not take into account) – type : attribute type – Ex : attribute size of a Beam. Image device • Beam. Image. h (header of the Beam. Image class ) – POGO code : Tango: : Dev. Long attr_size_write; • Beam. Image. cpp (impl. of the Beam. Image class ) – POGO code : Nothing ! – attr_size_write = initial. Size;

E 5 : Implementation : attributes n Writing mecanism Beam. Image (Device Impl. ) Beam. Image (CORBA Obj. ) write_attributes(Attr 1, Attr 2) always_executed_hook write_attr_hardware (Attr 1, Attr 2)

E 5 : Implementation : attributes n Writing mecanism – About write_attribut_hardware… • 1 call for n attributes to write • object : «writing» on the hardware (instruction) • update of variable members of type <…_write> – attr. get_write_value(attr_size_write) • exception removed beforehand (by TANGO) if … – val_min > valeur_utilisateur • or – Valeur_utilisateur > val_max • In that case … – no call to write_attribut_hardware ! – for no attribute !

E 5 : Implementation : attributes n READ_WRITE attribute – READ_WRITE = READ + WRITE • 2 variables member of the implementation class • instruction vs real value • <read part> – name : attr_{ATTR NAME}_read – type : pointer on the attribute type • <write part> – name : attr_{ATTR NAME}_write – type : attribute type – Ex : attribute scaling of a Beam. Image device • Beam. Image. h (header of the Beam. Image class) – Tango: : Dev. Double *attr_scaling_read; – Tango: : Dev. Double attr_scaling_write; • Beam. Image. cpp (impl. of the Beam. Image class ) – POGO code : Nothing ! – attr_scaling_read = new Tango: : Dev. Double; – attr_scaling_write = initial. Scaling;

E 5 : Implementation : attributes

E 5 : Implementation : miscellaneous n About the init_device… – Method linked to the initialisation of a device – Contents • Everything in line with the device init – Instanciations and memory allocations – Reading of the properties from the TANGO database – A constraint … • The exec of the TANGO Init commands (on the DServer and/or the device) causes the one of <init_device> • Memory leaks ! – A reflex … • Overload delete_device • De-allott everyting (re)allotted by init_device

E 5 : Implementation : miscellaneous n Case of a «device-client» – A device client of another device – Use API C++ • Class Tango: Device. Proxy • Cf. Section 5 of the programmer’s guide – An exemple : the Beam. Dim device • • • std: : string source_name(“formation-tango/beamimage/user 0”); Tango: : Device. Proxy *image_source; //connect to source image_source = new Tango: : Device. Proxy(source_name); Tango: : Device. Attribute result; //read image attribut result = image_source->read_attribute(“image”); //extract image from generic container into a std: : vector<Tango: : Dev. Long> image; result >> image;