Adding New Scripted Devices

This section describes the procedure for creating a new scripted device.

1. Create an entry in the database.dat file for the new device as described in Pseudo Motor Entry.
   • Set the responsibleDHS to 'self'.

   • Set the externalName parameter to the name of your new device file without the .tcl extension.

     Alternatively you can set the externalName to standardVirtualDevice. This would make the device a motor that simply holds a position. If you select the standardVirtualDevice, then this is the only step that you need to perform, and you can restart DCSS.

2. Create the new device file in the dcss devices directory: dcss/scripts/devices

   The file name should be the name of the new device (as listed in the database.dat file) with a .tcl extension. For example, the table_vert scripted device should have a file table_vert.tcl within the devices directory.

3. Within the new scripted device file define 5 TCL procedures, where deviceName is replaced by the name of the new scripted device.
   • proc deviceName_initialize {}

     This procedure is executed when DCSS starts up. This procedure may be empty, or it may be used to initialize variables associated with the scripted device.

     This is also the correct place to call the set_children, set_siblings, and set_observers functions as discussed in Device Relationships.

   • proc deviceName_set { newPosition}

     This is the procedure that is called when a motor configuration is initiated by the set command. The value being applied to the scripted device motor is passed in the newPosition. This procedure does not necessarily have to accept the new position, but can use the value to set other motors.

   • proc deviceName_move {newPosition}

     This is the procedure that is executed when an attempt is made to move the scripted device. The script is free to do whatever it wants, including moving other motors or calling scripted operations. If the script moves other motors, it is likely that these motors should be listed as children using the set_children command. However, this is not a requirement to moving other motors.

   • deviceName_update

     This procedure is called whenever the scripting engine has reason to believe that the scripted device's current position is out of date. This happens under the following conditions:

     • The scripting engine receives an update an a child motor of the scripted device.
     • The scripting engine receives an move complete on a child motor of the scripted device.
     • The scripting engine receives a configuration on a child motor of the scripted device.

   • proc deviceName_calculate {[child1 [child2 [child3]]]}

     This procedure is called by the scripting engine when determining if a child motor is allowed to move to a certain position without violating the parent's software limits. The arguments of this function are listed in the order that this function listed its children in the set_children command.

     This function must accept theoretical children positions and re-calculate a new position. It is common for the deviceName_update command to use this procedure to update its current position using current children motor positions.

4. Restart DCSS.