DESCRIPTION

SPring-8 (the 8-GeV Super Photon Ring in Hyogyo, Japan) has developed a distributed instrument control framework called MADOCA for operating the accelerator and which is also used at some beamlines. The framework has several layers. Support for the Equipment Manager layer that communicates directly with motor and counter devices was included in spec release 4.05.03 from September 1999. An em_io() user function was added shortly after in release 4.05.10 to allow sending arbitrary commands to devices.

Communication between spec and the Equipment Manager layer uses the remote procedure call (RPC) protocol. spec release 6.08.06 includes support for the MADOCA Request Server layer that sits above the Equipment Manager. Communication between spec and the Request Server is via TCP socket messages. In order to reflect the naming conventions used at SPring-8, the em_io() function has been renamed madoca_io(). A backward compatible em_io() macro is defined as madoca_io().

MADOCA MOTORS

MADOCA motors are identified by a string that includes information that selects the crate or device in which the individual motor controller resides. Motors in the same crate share a common prefix in that identification string. The controller configuration in spec's hardware configuration editor includes that prefix.

MADOCA motors are configured to use either the Equipment Manager RPC interface or the Request Server socket interface on the Devices screen of the configuration editor as follows:

Motor and Counter Device Configuration (Not CAMAC)

 MOTORS           DEVICE  ADDR <>MODE  NUM                       <>TYPE U#
 0  YES       host:bl_99               100  SP-8 MADOCA Motors (EM RPC)  0
 1  YES       host:bl_99     -         100  SP-8 MADOCA Motors (socket)  1
 2  YES host:10101:bl_99     -         100  SP-8 MADOCA Motors (socket)  2
 3  YES             host bl_99         100  SP-8 MADOCA Motors (socket)  3
 4  YES       host:10101 bl_99         100  SP-8 MADOCA Motors (socket)  4

For the RPC interface, the DEVICE column contains the hostname, a colon, then the motor prefix. The hostname is either a resolvable host name or an IP address.

For the socket interface, the DEVICE column contains a string in the form hostname:port:prefix. The TCP port number is optional. If missing, port 10101 will be used. The hostname is either a resolvable host name or an IP address. As an option, the prefix can be instead be entered in the ADDR column.

The value for the number of motors in the NUM column is not critical. It can be set equal to or higher than the number of motors in use.

Each entry is for a particular crate or controller. By default, motor names will formed using the prefix associated with the crate, followed by the string "_motor_", followed by the motor number, as set on the Motors screen. If another naming convention is used, the name after the common prefix can be configured for each motor either as a string under "Generic Parameter 1" on the standard optional motor parameter screen or as a parameter named "prefix" on the non-standard optional parameter screen.

Note, spec sets the software motor limits in the RPC server for each motor to agree with the software limits in the spec settings file. That is to say, software motor limits that could be obtained from the MADOCA server are ignored.

MADOCA COUNTERS

MADOCA counters and counter/timers devices are configured on the Devices screen of spec's hardware configuration editor. Either the RPC or socket interface can be configured. Devices can be configured as counter/timers or as counters only.

SCALERS           DEVICE  ADDR <>MODE  NUM                              <>TYPE U#
 0  YES       host:bl_99     1          10  SP-8 MADOCA Counter/Timer (EM RPC)  0
 1  YES       host:bl_99     1          10       SP-8 MADOCA Counters (EM RPC)  1
 2  YES       host:bl_99     1          10  SP-8 MADOCA Counter/Timer (socket)  2
 3  YES       host:bl_99     1          10       SP-8 MADOCA Counters (socket)  3
 4  YES host:10101:bl_99     1          10  SP-8 MADOCA Counter/Timer (socket)  4
 5  YES host:10101:bl_99     1          10       SP-8 MADOCA Counters (socket)  5

For the RPC interface, the DEVICE column contains the hostname, a colon, then the motor prefix. The hostname is either a resolvable host name or an IP address.

For the socket interface, the DEVICE column contains a string in the form hostname:port:prefix. The TCP port number is optional. If missing, port 10101 will be used. The hostname is either a resolvable host name or an IP address. In the ADDR column, enter the module number of the counter in the crate. The counter name will be formed by appending _counter_A or _counter_A_C to the prefix (depending on whether the command is for the unit or an individual channel), where A is the value of the ADDR field and C is the channel number of the counter from the Scalers screen.

THE madoca_io()/em_io() FUNCTION

Arbitrary MADOCA commands can be sent using the madoca_io([host, ] voc) function. When invoked with two arguments, the first argument host is a string containing the host name, such as "bl35vme0", while the second argument is the voc part of the command (verb-object-command?). If called with just the voc argument, the same host name as the previous em_io() call is used. If the command is a "get" voc, the reply is returned as a string. Otherwise the return value is a zero. If there is an error, the return value is -1.

To distinguish between RPC and socket calls, spec checks whether the host argument contains a colon followed by a port number. If it does, spec will use socket calls. Otherwise, the RPC interface will be used.