PySequencer message dialog

Remote Procedure Calls (RPC)

2025-01-20T23:01:11Z

Bsmith: /* Javascript */

{{Pagelinks}}

= RPC in a nutshell =

Midas uses a Remote Procedure Call (RPC) system to allow different midas clients to talk to each other directly. One client can issue a command to another, and the second client will perform some action and send a response back to the caller.

= Internal usage in midas =

Internally, midas uses the RPC system to handle run transitions, ODB hotlinks and more.

For example, if you start a run using the web interface, mhttpd (the webserver) will send an <code>RPC_RC_TRANSITION</code> message to clients that want to handle the begin-of-run transition. Each client responds with whether it's okay for the transition to proceed.

Any clients that are running on a remote server use RPC for all their communications with midas. The special mserver program (running on the main host) is responsible for handling these requests. For example, whereas a local client can read an ODB value directly from shared memory on the main host; a remote client instead issues an RPC call to mserver, which reads the value from shared memory and returns it to the caller.

At the very lowest level, each program checks if it has any outstanding RPC requests to handle as part of the <code>cm_yield()</code> function, which should be called periodically by every midas client.

= Use in user code - JRPC =

One of the RPC commands, <code>RPC_JRPC</code>, is very flexible and allows the user to easily integrate custom commands into their programs. There are interfaces in C++, python and javascript.

The calling code specifies:
* The program it wants to talk to
* The command it wants to issue (generally a short string)
* Some arguments (either plain text or JSON)

The client then:
* Decides what to do based on the command and arguments
* Responds with a status code and text message (either plain text or JSON)

Some example uses of this system are:
* Have a client turn some equipment off when the user clicks a button on a webpage.
* Offload some complex calculations to another program (e.g. if your main client is in C++ but it's much easier to implement the calculations in python).
* Implement a web-based plot display that gets data as JSON from a python/C++ client
* Much much more...

== Benefits vs ODB hotlinks ==

Often users implement inter-process communication using ODB hotlinks (where a client can say "tell me whenever /Path/to/something in the ODB changes"). Although this works for simple cases, the JRPC system is much more flexible and robust.

* Much easier to specify arguments. Avoids race conditions if you were to use multiple ODB keys to tell the target what to do.
* There is no "competition" for the ODB key(s). Multiple clients can call the same RPC without interfering with each other.
* More flexible response format as you can return a (very) long string. Alternatives would be to put the response in an ODB value (limited maximum length) or in a file on disk (extra overhead, and possibly annoying to deal with stale files over NFS).

== Registering your JRPC handler ==

If you want other midas clients to be able to talk to you, you need to register an RPC handler. You specify the RPC you're listening for (<code>RPC_JRPC</code> in this case) and a function that midas should call.

=== C++ ===

The midas function to use is:

// * id - RPC_JRPC in this case
// * func - Function to call (see below)
INT cm_register_function(INT id, INT(*func)(INT, void **))

The callback function (<code>func</code> in the above example) should look something like the below:

// * index is the RPC id (RPC_JRPC in our case).
// * prpc_param is a list of pointers that we need to cast to the appropriate types:
// - [0] is a C-string containing the "command"
// - [1] is a C-string containing the "arguments"
// - [2] is a C-string where you can write a response
// - [3] is an integer stating the maximum response length the caller expects
// * The function should return SUCCESS if everything is okay.
INT my_rpc_callback(INT index, void *prpc_param[]) {
const char* cmd = CSTRING(0);
const char* args = CSTRING(1);
char* return_buf = CSTRING(2);
int return_max_length = CINT(3);

if (strcmp(cmd, "add_one") == 0) {
// Silly example that parses `args` as a number and returns x+1 in return_buf
int val = atoi(args);
val += 1;
sprintf(return_buf, "%d", val);
} else {
// Up to you how to handle error conditions - report in return_buf or via return value.
sprintf(return_buf, "err");
}

return SUCCESS;
}

...

cm_register_function(RPC_JRPC, my_rpc_callback);

=== C++ (TMFE) ===

In the [[Frontend_user_code_(object_oriented_-_TMFE)|TMFE]] framework, an RPC handler has already been registered.

You should implement the <code>HandleRpc()</code> function in your class that derives from <code>TMFeEquipment</code>:

TMFeResult HandleRpc(const char* cmd, const char* args, std::string& result) {
if (strcmp(cmd, "add_one") == 0) {
// Silly example that parses `args` as a number and returns x+1 as the result
int val = atoi(args);
val += 1;
sprintf(return_buf, "%d", val);
} else {
// In TMFE, you must report errors via the result.
result = "err";
}

return TMFeOk();
}

=== Python ===

The [[Python|python]] interface is very similar to the C++ interface for registering RPC callbacks.

In <code>midas.client</code> you call <code>register_jrpc_callback(callback, return_success_even_on_failure)</code>.

The callback function should be defined as <code>def rpc_handler(client, cmd, args, max_len)</code>, where the arguments are:
* client (midas.client.MidasClient)
* cmd (str) - The command user wants to execute
* args (str) - Other arguments the user supplied
* max_len (int) - The maximum string length the user accepts in the return value

The callback function should return either a tuple of (int, str) or just an int. The integer should be a status code from midas.status_codes. The string, if present, should be any text that should be returned to the caller.

The <code>return_success_even_on_failure</code> argument to <code>register_jrpc_callback</code> deals with a subtlety regarding mjsonrpc (the web interface for calling JRPC functions), as it does not return any message if the status code isn't "SUCCESS". This can be annoying if you want to show a specific error message to the user, and not have them trawl through the midas message log. If you set this parameter to False, then you get the "normal" behaviour, where the returned status code and result string are exactly what is returned from the callback function. If you set this parameter to True, then the status code will always be "SUCCESS", and the result string will be JSON-encoded text of the form <code>{"code": 604, "msg": "Some error message"}</code>.

Example code is:

def my_rpc_callback(client, cmd, args, max_len):
ret_int = midas.status_codes["SUCCESS"]
ret_str = ""

if cmd == "add_one":
val = int(args)
val = val + 1

ret_str = str(val)
else:
ret_int = midas.status_codes["FE_ERR_DRIVER"]
ret_str = "err"

return (ret_int, ret_str)

if __name__ == "__main__":
client = midas.client.MidasClient("pytest")

# Register our function.
client.register_jrpc_callback(my_rpc_callback, True)

# Spin forever. Program can be killed by Ctrl+C or
# "Stop Program" through mhttpd.
while True:
client.communicate(10)

== Calling JRPC on other clients ==

In all languages, you specify which program you want to talk to, a command and some arguments. You will then be returned a status code and a message string. As you are the person writing both sides of the JRPC communication, it is up to you to define what format the arguments and returned message take (e.g. plain text or JSON).

=== C++ ===

In C++ you use <code>cm_connect_client()</code> and <code>rpc_client_call()</code> to call JRPC on another program.

INT status = SUCCESS;

// First connect to the other client
HNDLE hConn = 0;
status = cm_connect_client("other_program", &hConn);

if (status != SUCCESS) {return;}

// Then build arguments and call the RPC
std::string cmd = "add_one";
std::string args = "6";
char buf[1000];
int buf_length = 1000;

status = rpc_client_call(hConn, RPC_JRPC, cmd.c_str(), args.c_str(), buf, buf_length);

if (status != SUCCESS) {return;}

// 'buf' should contain "7" in our example.

Note that [https://github.com/nlohmann/json/raw/develop/single_include/nlohmann/json.hpp json.hpp] is a very useful tool if you want to use JSON in your C++ code.

=== Python ===

In python you use the <code>connect_to_other_client()</code> and <code>jrpc_client_call()</code> functions in <code>midas.client</code>.

client = midas.client.MidasClient("my_program")

# First connect to the other client
other = client.connect_to_other_client("other_program")

# Then build arguments and call the RPC
command = "add_one"
args = "6"
retval = client.jrpc_client_call(other, command, args)

# retval should now contain "7"
# An exception will be raised if the other program returned a non-SUCCESS status.

=== Javascript ===

In javascript you use the <code>mjsonrpc_call</code> function.

// In JS, client to connect to is specified as a parameter
let params = Object();
params.client_name = "other_program";
params.cmd = "add_one";
params.args = "6";
params.max_reply_length = 100000; // Optional, defaults to 1024 bytes

// Call RPC asynchronously. Returns a Promise that you deal with using "then()"
mjsonrpc_call("jrpc", params).then(function(rpc) {
if (rpc.result.status != 1) {
// Other program reported a problem
}

// rpc.result.reply should contain "7"
}).catch(function(error) {
mjsonrpc_error_alert(error);
});

Remote Procedure Calls (RPC)

2025-01-20T18:34:34Z

Bsmith:

{{Pagelinks}}

= RPC in a nutshell =

Midas uses a Remote Procedure Call (RPC) system to allow different midas clients to talk to each other directly. One client can issue a command to another, and the second client will perform some action and send a response back to the caller.

= Internal usage in midas =

Internally, midas uses the RPC system to handle run transitions, ODB hotlinks and more.

For example, if you start a run using the web interface, mhttpd (the webserver) will send an <code>RPC_RC_TRANSITION</code> message to clients that want to handle the begin-of-run transition. Each client responds with whether it's okay for the transition to proceed.

Any clients that are running on a remote server use RPC for all their communications with midas. The special mserver program (running on the main host) is responsible for handling these requests. For example, whereas a local client can read an ODB value directly from shared memory on the main host; a remote client instead issues an RPC call to mserver, which reads the value from shared memory and returns it to the caller.

At the very lowest level, each program checks if it has any outstanding RPC requests to handle as part of the <code>cm_yield()</code> function, which should be called periodically by every midas client.

= Use in user code - JRPC =

One of the RPC commands, <code>RPC_JRPC</code>, is very flexible and allows the user to easily integrate custom commands into their programs. There are interfaces in C++, python and javascript.

The calling code specifies:
* The program it wants to talk to
* The command it wants to issue (generally a short string)
* Some arguments (either plain text or JSON)

The client then:
* Decides what to do based on the command and arguments
* Responds with a status code and text message (either plain text or JSON)

Some example uses of this system are:
* Have a client turn some equipment off when the user clicks a button on a webpage.
* Offload some complex calculations to another program (e.g. if your main client is in C++ but it's much easier to implement the calculations in python).
* Implement a web-based plot display that gets data as JSON from a python/C++ client
* Much much more...

== Benefits vs ODB hotlinks ==

Often users implement inter-process communication using ODB hotlinks (where a client can say "tell me whenever /Path/to/something in the ODB changes"). Although this works for simple cases, the JRPC system is much more flexible and robust.

* Much easier to specify arguments. Avoids race conditions if you were to use multiple ODB keys to tell the target what to do.
* There is no "competition" for the ODB key(s). Multiple clients can call the same RPC without interfering with each other.
* More flexible response format as you can return a (very) long string. Alternatives would be to put the response in an ODB value (limited maximum length) or in a file on disk (extra overhead, and possibly annoying to deal with stale files over NFS).

== Registering your JRPC handler ==

If you want other midas clients to be able to talk to you, you need to register an RPC handler. You specify the RPC you're listening for (<code>RPC_JRPC</code> in this case) and a function that midas should call.

=== C++ ===

The midas function to use is:

// * id - RPC_JRPC in this case
// * func - Function to call (see below)
INT cm_register_function(INT id, INT(*func)(INT, void **))

The callback function (<code>func</code> in the above example) should look something like the below:

// * index is the RPC id (RPC_JRPC in our case).
// * prpc_param is a list of pointers that we need to cast to the appropriate types:
// - [0] is a C-string containing the "command"
// - [1] is a C-string containing the "arguments"
// - [2] is a C-string where you can write a response
// - [3] is an integer stating the maximum response length the caller expects
// * The function should return SUCCESS if everything is okay.
INT my_rpc_callback(INT index, void *prpc_param[]) {
const char* cmd = CSTRING(0);
const char* args = CSTRING(1);
char* return_buf = CSTRING(2);
int return_max_length = CINT(3);

if (strcmp(cmd, "add_one") == 0) {
// Silly example that parses `args` as a number and returns x+1 in return_buf
int val = atoi(args);
val += 1;
sprintf(return_buf, "%d", val);
} else {
// Up to you how to handle error conditions - report in return_buf or via return value.
sprintf(return_buf, "err");
}

return SUCCESS;
}

...

cm_register_function(RPC_JRPC, my_rpc_callback);

=== C++ (TMFE) ===

In the [[Frontend_user_code_(object_oriented_-_TMFE)|TMFE]] framework, an RPC handler has already been registered.

You should implement the <code>HandleRpc()</code> function in your class that derives from <code>TMFeEquipment</code>:

TMFeResult HandleRpc(const char* cmd, const char* args, std::string& result) {
if (strcmp(cmd, "add_one") == 0) {
// Silly example that parses `args` as a number and returns x+1 as the result
int val = atoi(args);
val += 1;
sprintf(return_buf, "%d", val);
} else {
// In TMFE, you must report errors via the result.
result = "err";
}

return TMFeOk();
}

=== Python ===

The [[Python|python]] interface is very similar to the C++ interface for registering RPC callbacks.

In <code>midas.client</code> you call <code>register_jrpc_callback(callback, return_success_even_on_failure)</code>.

The callback function should be defined as <code>def rpc_handler(client, cmd, args, max_len)</code>, where the arguments are:
* client (midas.client.MidasClient)
* cmd (str) - The command user wants to execute
* args (str) - Other arguments the user supplied
* max_len (int) - The maximum string length the user accepts in the return value

The callback function should return either a tuple of (int, str) or just an int. The integer should be a status code from midas.status_codes. The string, if present, should be any text that should be returned to the caller.

The <code>return_success_even_on_failure</code> argument to <code>register_jrpc_callback</code> deals with a subtlety regarding mjsonrpc (the web interface for calling JRPC functions), as it does not return any message if the status code isn't "SUCCESS". This can be annoying if you want to show a specific error message to the user, and not have them trawl through the midas message log. If you set this parameter to False, then you get the "normal" behaviour, where the returned status code and result string are exactly what is returned from the callback function. If you set this parameter to True, then the status code will always be "SUCCESS", and the result string will be JSON-encoded text of the form <code>{"code": 604, "msg": "Some error message"}</code>.

Example code is:

def my_rpc_callback(client, cmd, args, max_len):
ret_int = midas.status_codes["SUCCESS"]
ret_str = ""

if cmd == "add_one":
val = int(args)
val = val + 1

ret_str = str(val)
else:
ret_int = midas.status_codes["FE_ERR_DRIVER"]
ret_str = "err"

return (ret_int, ret_str)

if __name__ == "__main__":
client = midas.client.MidasClient("pytest")

# Register our function.
client.register_jrpc_callback(my_rpc_callback, True)

# Spin forever. Program can be killed by Ctrl+C or
# "Stop Program" through mhttpd.
while True:
client.communicate(10)

== Calling JRPC on other clients ==

In all languages, you specify which program you want to talk to, a command and some arguments. You will then be returned a status code and a message string. As you are the person writing both sides of the JRPC communication, it is up to you to define what format the arguments and returned message take (e.g. plain text or JSON).

=== C++ ===

In C++ you use <code>cm_connect_client()</code> and <code>rpc_client_call()</code> to call JRPC on another program.

INT status = SUCCESS;

// First connect to the other client
HNDLE hConn = 0;
status = cm_connect_client("other_program", &hConn);

if (status != SUCCESS) {return;}

// Then build arguments and call the RPC
std::string cmd = "add_one";
std::string args = "6";
char buf[1000];
int buf_length = 1000;

status = rpc_client_call(hConn, RPC_JRPC, cmd.c_str(), args.c_str(), buf, buf_length);

if (status != SUCCESS) {return;}

// 'buf' should contain "7" in our example.

Note that [https://github.com/nlohmann/json/raw/develop/single_include/nlohmann/json.hpp json.hpp] is a very useful tool if you want to use JSON in your C++ code.

=== Python ===

In python you use the <code>connect_to_other_client()</code> and <code>jrpc_client_call()</code> functions in <code>midas.client</code>.

client = midas.client.MidasClient("my_program")

# First connect to the other client
other = client.connect_to_other_client("other_program")

# Then build arguments and call the RPC
command = "add_one"
args = "6"
retval = client.jrpc_client_call(other, command, args)

# retval should now contain "7"
# An exception will be raised if the other program returned a non-SUCCESS status.

=== Javascript ===

In javascript you use the <code>mjsonrpc_call</code> function.

// In JS, client to connect to is specified as a parameter
let params = Object();
params.client_name = "other_program";
params.cmd = "add_one";
params.args = "6";

// Call RPC asynchronously. Returns a Promise that you deal with using "then()"
mjsonrpc_call("jrpc", params).then(function(rpc) {
if (rpc.result.status != 1) {
// Other program reported a problem
}

// rpc.result.reply should contain "7"
}).catch(function(error) {
mjsonrpc_error_alert(error);
});

Frontend user code

2025-01-09T22:41:32Z

Bsmith: /* Compilation using CMake */

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Frontend Operation]]
* [[Frontend Application]]
* [[Equipment List Parameters]]
* [[Slow Control System]]
* [[Equipment Flags]]
* [[Event Notification (Hot-Link)]]
</div>

= Introduction =
This section describes the features of the user-written part of a "C-style" [[Frontend Operation#Frontend|Frontend]], referred to here as '''frontend.c'''.

You can also write frontends using [[Frontend_user_code_(object_oriented_-_TMFE)|object-oriented C++ (TMFE)]] or [[Python]].

The frontend system has evolved over the decades, and contains some legacy features that are not often used (e.g. interrupt handlers). For backwards-compatibility, these features are still present, but this does require a bit more boiler-plate code to be written for each frontend. We will first document every feature supported by the frontend system, then explain a slightly more user-friendly wrapper (mfed.cxx) that helps reduce the amount of boiler-plate needed for a new frontend.

= Frontend Templates =
To make a user-written or custom frontend, users will usually modify one of the '''templates''' provided in the MIDAS package
under [[Environment Variables#MIDASSYS|$MIDASSYS]]/examples/ for their particular hardware and other requirements. Make sure to pick the closest template, e.g. if writing a [[Slow Control System|Slow Control]] frontend, pick a slow-control template. For each example frontend, a Makefile is also provided.

A partial list of the templates provided is shown below:
{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Hardware
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Filename
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Directory (MIDAS package)
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Purpose
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Language

|-
|VME
|fevmemodules.c
| $MIDASSYS/examples/Triumf/c/
| Access to VME modules
| C

|-
|VME
|fevme.cxx
| $MIDASSYS/examples/Triumf/c++/
| Access to VME modules
| C++

|-
|CAMAC
|frontend.c
| $MIDASSYS/examples/experiment/
| Access to CAMAC modules
| C

|-
|
|mtfe.c
| $MIDASSYS/examples/mtfe/
| '''Multithreaded''' using ring buffer
| C

|-
| Wiener CC-USB
|feccusb.cxx
| $MIDASSYS/examples/mtfe/
| CAMAC/USB demo
| C++

|-
|RS485 bus
|mscb_fe.c
| $MIDASSYS/examples/slowcont/
| '''Slow control''' with [https://midas.psi.ch/mscb/ MSCB]
| C

|-
|EPICS
|frontend.c
| $MIDASSYS/examples/epics/
| '''Slow controls'''
| C

|-
|Camac
|ebfe.c
| $MIDASSYS/examples/eventbuilder/
| '''Event Builder''' (with [[mevb]])
| C

|-
|
|frontend.cxx
| $MIDASSYS/examples/experiment/
| '''mfed''' (wrapper to simplify writing a frontend)
| C++

|}

The features of a typical frontend program are best explained by reference to examples of the user code
provided in the Midas Package.

=Frontend code=
Note that there are several kinds of frontend used for different purposes, e.g.
* frontend to read VME or CAMAC hardware, using interrupt or polling (e.g. to read experimental data)
* multithreaded frontend where polling can be in a separate thread
* slow control frontend (can be multithreaded) see also [[Slow Control System]]
* etc.

Templates for many types of user frontend code are provided in the MIDAS packages (see [[#Frontend Templates]]).

The following sections refer to these templates.
Most of the examples are taken from the [https://bitbucket.org/tmidas/midas/src/develop/examples/basic/largefe.cxx largefe.cxx example]. Documentation on the MIDAS library subroutines to access the ODB (some of which are used in the examples below) can be found in the [[ODB_Access_and_Use|ODB access page]].

The user frontend code is then compiled and linked with the system part and the MIDAS library
(see [[Frontend Operation#Frontend|Frontend Task]]). Makefiles are provided with the templates that can be modified as needed.

== Access to command line parameters ==
The function '''mfe_get_args''' gives access to the [[Frontend Application|Frontend]] command line parameters.

This example shows how to use it in the frontend user code:

int argc;
char **argv;
mfe_get_args(&argc, &argv);
for (int i = 0; i < argc; i++) {
// Use argv[i]
}

See [[Frontend_Application#Arguments|Frontend Application Arguments]] for the arguments that are handled automatically by the frontend system.

==Include files==
The following example (from template frontend file ''$MIDASSYS/examples/basic/largefe.cxx'') shows the standard include files needed for a frontend. The user may add any other include files as needed (e.g. those needed for VME access).

Some legacy frontends may include the '''[[ODB#experim.h include file|experim.h]]''' file. This was an old way of accessing the ODB, but was not very user-friendly when the ODB structure needed to change.

The example below shows a typical list of include files for a frontend:

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

'''<div id="Frontend Name"></div>'''
==Global Declarations==
The following example (from template frontend file fevmemodules.c - see [[#Frontend Templates]]) shows the global declaration. The declarations are system wide. Some may be changed to suit the user, but none should not be removed.

; frontend_name : This value can be modified to reflect the purpose of the code
; frontend_call_loop : If set to TRUE, the function frontend_loop() gets called very frequently. If FALSE, frontend_loop() does not run. The user can add suitable code to this routine if desired (e.g. to check for a condition).
; display_period : The time interval (defined in milliseconds) between the refresh of a frontend status display. The value of zero disables the display. If the frontend is started in the background with the display enabled, the stdout should be redirected to the null device to prevent the process from hanging.
; max_event_size : specifies the maximum size (in bytes) of the expected event.
; event_buffer_size : specifies the maximum size (in bytes) of the buffer to be allocated by the system.
; equipment_common_overwrite : whether the definitions in the EQUIPMENT struct override those in the /Equipment/largefe/Common section of the ODB. If FALSE, the values in the struct will be used the first time the program runs, then the ODB values will be used afterwards (e.g. allowing you to change the period of a [[#Event_Types_and_Triggers|periodic equipment]] via the ODB).

See below for an example of global declarations from a frontend.

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/* frontend_loop is called periodically if this variable is TRUE */
BOOL frontend_call_loop = TRUE;

/* a frontend status page is displayed with this frequency in ms */
INT display_period = 0;

/* maximum event size produced by this frontend */
INT max_event_size = 10000;

/* maximum event size for fragmented events (EQ_FRAGMENTED) */
INT max_event_size_frag = 5 * 1024 * 1024;

/* buffer size to hold events */
INT event_buffer_size = 10 * 10000;

/* whether the values in EQUIPMENT struct override ODB values */
BOOL equipment_common_overwrite = FALSE;

==System Function Declarations==

These lines declare the pre-defined system functions which should be present.

INT frontend_init();
INT frontend_exit();
INT begin_of_run(INT run_number, char *error);
INT end_of_run(INT run_number, char *error);
INT pause_run(INT run_number, char *error);
INT resume_run(INT run_number, char *error);
INT frontend_loop();

==Readout Function Declarations==
Following the previous group is a second group of declarations, which define the readout functions. These depend on the defined equipments, and run when the respective equipment is triggered. In this example, one equipment will be defined, so there is one declaration. The user functions will be described in detail in later sections.

INT read_large_event(char *pevent, INT off);

If using an interrupt, callback function prototypes are also included

extern void interrupt_routine(void);
void register_cnaf_callback(int debug);

==Equipment List==

This list of structs defines the behaviour of your frontend (e.g. [[#Event_Types_and_Triggers|periodic or polled equipment]]). See [[Equipment List Parameters|Equipment List]] for full documentation of the entries.

Note that these are the default values for each equipment (used the very first time a frontend is run). If [[#Global declarations|equipment_common_overwrite]] is FALSE, then some of the values will subsequently be read from the ODB instead. If [[#Global declarations|equipment_common_overwrite]] is TRUE, then the ODB will be updated with the coded values each time the program runs.

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

In the case of a polled equipment, the struct would be of the form:

EQUIPMENT equipment[] = {
{ "Trigger", // equipment name
{
...
<b>EQ_POLLED</b>, // equipment type
...
500, // poll for 500ms
...
"", "", "",},
read_my_event, // readout routine
...

In the case of a periodic equipment, the struct would be of the form:

EQUIPMENT equipment[] = {
{ "Scaler", // equipment name
{
...
EQ_PERIODIC // equipment type
...
10000, // period (read every 10s)
...
"", "", "",},
read_my_event, // readout routine
...

==Sequence of Operations in the frontend==

The following table shows the sequence of operations of the [[Frontend Operation#Frontend|Frontend]] System functions. These functions must be implemented in the user's code (but may be as simple as just returning <code>SUCCESS</code> if the function is not relevant for your use case). These functions are called by ''mfe.cxx'' at the appropriate time. The System Transition functions are associated with a particular [[Run States and Transitions|Run Transition]] as shown below:

{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="0" cellpadding="2" cellspacing="2"

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | System Function
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | System Transition Function
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Associated [[Run States and Transitions|Transition]]
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Action

|-
| frontend_init()
|
|
| Runs once after system initialization, before Equipment registration.

|-
|
| begin_of_run()
| style="color:blue"|TR_START
| Runs after system statistics reset at each begin-of-run request.

|-
|
| pause_run()
| style="color:blue"|TR_PAUSE
| Runs at each pause-run request.

|-
|
| resume_run()
| style="color:blue"|TR_RESUME
| Runs at each resume-run request.

|-
|
| end_of_run()
| style="color:blue"|TR_STOP
| Runs at each end-of-run request.

|-
| frontend_exit()
|
|
| Runs once before any Slow Control Equipment exit
|}

Each defined Equipment has the option to force itself to run at individual transition times (see Equipment [[Equipment List Parameters#ReadOn|ReadOn Flag]]), so that its equipment function will be called on a certain transition (or combination of transitions).

The system transition functions all run '''prior to''' the equipment functions. This gives the system the chance to take basic action on the transition request (e.g. enable/disable interrupt) before the equipment runs. All the transition routines run with a [[Run States and Transitions#Default Transition Sequency Numbers|Transition Sequence number]] of 500 (the default). This allows users to add additional functions in the frontend that will run before or after any of the transitions (such as a prestart() or a poststop() function). See [[Run States and Transitions#Run Transition Priority|Run Transition Priority]] for more information.

==Function frontend_init ==

No parameters.

This function runs '''once only''' at the application startup. Users may perform hardware checking, loading/setting of global variables, mapping of required ODB structures (see [[ODB#experim.h include file|experim.h include file]]),
[[Event Notification (Hot-Link)#How to set up a Hot-Link|setting up hot-links]] etc. in frontend_init(), e.g.

INT frontend_init()
{
set_equipment_status(equipment[0].name, "Initializing...", "yellow");
....
set_equipment_status(equipment[0].name, "OK", "green");

return SUCCESS;
}

===Reporting Equipment Status===
If running with the webserver [[mhttpd]], a frontend can send an update to the [[Status Page]], to report on its progress, using the function set_equipment_status() (see above example). This is useful when hardware can take a long time to respond.

==Function begin_of_run==

Parameters:
* INT '''run number''' provides the number of the current run being started
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

This function is called every time a run start transition occurs, i.e. at begin-of-run. It allows the updating of user parameters, and the loading/setup/clearing of hardware. At the exit of this function, the acquisition should be armed and ready to test the interrupt (if used), e.g.

INT begin_of_run (INT runnumber, char * error)
{
// Read/validate some settings from the ODB (and return FE_ERR_ODB if there's a problem).
// Apply them to the hardware (and return FE_ERR_HW if there's a problem).
// etc...
return SUCCESS;
}

==Functions pause/resume_run==

Parameters:
* INT '''run number''' provides the number of the current run being paused/resumed.
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

These two functions are called upon "Pause" and "Resume" command respectively. Any code relevant to the upcoming run state can be included,e.g.

INT pause_run (INT run_number, char * error)
{
disable_trigger();
// Disable interrupt
inRun = 0;
mvme_write_value(myvme, VLAM_BASE+4, inRun);
return SUCCESS;
}
//
INT resume_run (INT run_number, char * error)
{
enable_trigger();
inRun = 1;
mvme_write_value(myvme, VLAM_BASE+4, inRun);
return SUCCESS;
}

==Function end_run==

Parameters:
* INT '''run number''' provides the number of the current run being ended.
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

This function is called at every "stop run" transition. It provides the opportunity to disable the hardware, e.g.

INT end_of_run(INT run_number, char *error)
{
// Stop the hardware.
// etc...
return SUCCESS;
}

==Function frontend_exit==

Parameters: none

The function runs when the frontend program is shut down. Can be used to release any locked resources like memory, communications ports etc. e.g.

function frontend_exit()
{
mvme_close(gVme);
return;
}

==Function frontend_loop==

Parameters: none

If [[#Global declarations|frontend_call_loop]] is set to TRUE, this routine is called when the frontend is idle and at least once between every event. You could use it for example to check if there has been a timeout from hardware.

...
BOOL frontend_call_loop = TRUE;
...

INT frontend_loop()
{
// Implement any code that needs to be run very frequently
return SUCCESS;
}

==Event Types and Triggers==
The frontend supports several different types of [[Frontend Operation#Frontend event triggers|event trigger]]. The event trigger type is specified by the [[Equipment Flags|Equipment Flag]] in the [[Equipment List Parameters|Equipment Declaration]]. Common event types are "polled events" where the Equipment Flag is [[Equipment Flags#EQ_POLLED|EQ_POLLED]], "interrupts events" where the Flag is [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]], and "periodic events" where the Flag is [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]. The name of the associated readout routine is specified in the [[Equipment List Parameters|Equipment Declaration]] for each event type.

Polled and interrupt events (see [[#Event Types|Event Types]]) require several extra functions to handle the hardware that periodic events do not require. These are described below.

Note that each frontend may contain:
* zero or one polled equipments
* zero or one interrupt equipments
* any number of periodic equipments

==Function poll_event==
Parameters:
* INT '''source'''
* INT '''count'''
* BOOL '''test'''

If the [[Equipment List Parameters#Equipment Type|Equipment Type]] is EQ_POLLED, the poll_event() routine will be called as often as possible over the corresponding poll time (e.g. 500ms) given by each polling equipment.

The user must provide suitable code in the routine poll_event(), e.g. reading a register from a VME module to see if any data is available

INT poll_event(INT source, INT count, BOOL test)
{
/* Polling routine for events. Returns TRUE if event is available. If test equals TRUE, don't return.
The test flag is used to time the polling
*/
int i;
int lam = 0;
//
for (i = 0; i < count; i++, lam++) {
lam = vmeio_CsrRead(myvme, VMEIO_BASE);
if (lam)
if (!test)
return lam;
}
return 0;
}

An [[#Event Readout routine|event readout routine]] must also be provided by the user.

==Function interrupt_configure==
* INT '''cmd'''
* INT '''source'''
* PTYPE '''adr'''

If the [[Equipment List Parameters#Equipment Type|Equipment Type]] is EQ_INTERRUPT, an interrupt configuration routine called interrupt_configure() must be provided by the user.
The interrupt configuration routine has the following declaration:

/*-- Interrupt configuration --------------------------*/
INT interrupt_configure(INT cmd, INT source, PTYPE adr)
{
int vec = 0;
switch (cmd)
{
case CMD_INTERRUPT_ENABLE:
if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x1);
break;
//
case CMD_INTERRUPT_DISABLE:
if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x0);
break;
//
case CMD_INTERRUPT_ATTACH:
mvme_set_dmode(myvme, MVME_DMODE_D32);
mvme_interrupt_attach(myvme, INT_LEVEL, INT_VECTOR,
(void *)adr, &myinfo);
mvme_write_value(myvme, VLAM_BASE+0x10, INT_VECTOR);
vec = mvme_read_value(myvme, VLAM_BASE+0x10);
printf("Interrupt Attached to 0x%x for vector:0x%x\n",
adr, vec&0xFF);
break;
//
case CMD_INTERRUPT_DETACH:
printf("Interrupt Detach\n");
break;
}
return SUCCESS;
}

Under the four commands listed above, the user must implement the hardware operation needed to perform the requested action. In the Midas drivers directory examples can be found of such an interrupt code for CAMAC. See source code such as hyt1331.c,ces8210.c

An [[#Event Readout routine|event readout routine]] must also be provided by the user in the frontend.

==Event Readout routine==

An event readout routine is required for all equipment, and is responsible for sending the actual data to midas. The framework calls the event readout routine whenever an equipment has been triggered (e.g. periodicially, or because poll_event() returned TRUE for a polled equipment etc). The function is of the form

INT function_name ( char *pevent ... )
{
INT event_size;
........ // read data from hardware
........ // pack into banks depending on format
........
return (event_size);
}

where the first argument of the readout function (pevent) provides the pointer to the newly constructed event, and points to the first valid location for storing the data.
;NOTE
* <b>The return value is the event size</b>, and must be the number of bytes collected in this function. This is different to almost every other function in midas (where the return value is a status code).
* You can return 0 if you've decided you don't actually want to write this event.
* The event serial number will be incremented by one for every call to the readout routine, as long as the returned size is non-zero.

===General readout function===

A readout function is needed to send out data. This is done using one of the supported [[Event Structure|event structures]] usually [[Event Structure#MIDAS Format Event|"MIDAS" format]] data banks. The bank format ("MIDAS" in the example above) is declared in the [[Equipment List Parameters]] [[Equipment List Parameters#Format|Format]] field.

An example of a scaler readout routine read_scaler_event() where the data is read out into [[MIDAS Event Construction|MIDAS data banks]] is shown below.

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

/* create bank (bank names must be 4 chars long) */
bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);

/* fill data (just dummy values in this case) */
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);

/* close the bank */
bk_close(pevent, pddata);

/* return the number of bytes we wrote */
return bk_size(pevent);
}

Some other examples of event readout routines in this document are
* [[Event Structure#FIXED Event Construction|FIXED Format event construction]]
* [[Super Event]] construction
* [[Slow Control System|Slow Control]]

Many other examples of readout routines can be found in the [[#Frontend Templates|frontend templates]] in the MIDAS package.

===Polled or Interrupt readout routine===
In the case of a [[#Polled and Interrupt Events|Polled or Interrupt event]], the content of the memory location pointed to by '''pevent''' (see [[#Event Readout routine|Event Readout routine]]) prior to its use in the readout function, contains the interrupt source bitwise register. This feature can be exploited in order to identify which hardware module has triggered the readout when multiple interrupts have been assigned to the same readout function.

The examples below show a VME interrupt source for a given equipment. Depending whether USE_INT is defined, the Equipment will either use a Polled or an Interrupt mechanism.
The [[Equipment List Parameters|Equipment declaration]] is of the form:

EQUIPMENT equipment[] = {
//
{"Trigger", /* equipment name */
...
#ifdef USE_INT
EQ_INTERRUPT, /* equipment type */
#else
EQ_POLLED, /* equipment type */
#endif
/* interrupt source: crate 0, all stations */
LAM_SOURCE(0, 0x0),
....
"", "", "",
},
read_trigger_event, /* readout routine */
NULL, NULL,
trigger_bank_list,
}

Note that the [[Macros#CAMAC Macros|LAM_SOURCE macro]] simply codes the parameters into a bitwise register.

The readout routine would contains code such as

INT read_trigger_event(char *pevent, INT off)
{
#if defined VADC0_CODE
DWORD *pdata;
#endif
//
#if defined VADC0_CODE
/* read ADC0 data */
v792_EvtCntRead(myvme, VADC0_BASE, &evtcnt);
........
/* Read Event */
v792_EventRead(myvme, VADC0_BASE, pdata, &nentry);
........
v792_DataClear(myvme, VADC0_BASE);
#endif
//
........
return (size);
}

The data will be packed into banks as described for the [[General readout function|general readout function]] above.
The example <code>$MIDASSYS/examples/Triumf/c/fevmemodules.c</code> contains a complete example of read_trigger_event().

==Manual Trigger==
Another type of [[Frontend Operation#Frontend event trigger|frontend event trigger]] supported is the "manual trigger", where the Equipment Flag is [[Equipment Flags#EQ_MANUAL_TRIGGER|EQ_MANUAL_TRIGGER]]. This flag means that an event can be triggered through the URL <code>?cmd=Trigger/<equipment_name></code> (e.g. <code>http://my.host:8080/?cmd=Trigger/MyEquipmentName</code>). If you add this URL to the [[/Alias ODB tree|/Alias]] part of the ODB, then a link will appear on midas webpages that can be clicked to trigger an event.

In some cases, the same readout code may be used for two types of event: a manual trigger and (say) a poll event. It is possible to determine whether the readout of an event was triggered by a manual trigger or a regular trigger by adding a call to the [[MIDAS Event Header Macros|event header Macro]] DATA_SIZE in the readout routine:

flag = DATA_SIZE(pevent);

If the result is
* flag = 0 normal call
* flag = 1 manual trigger

It is also possible for a backend MIDAS client (such as an analyzer or custom data archiver) to trigger a manual trigger event. The client controls when an event is sent by means of
a function that requests an event by triggering the event sending mechanism with a RPC call.

With a frontend Equipment declaration of a manually triggered event of the form:

{ "Histo", /* equipment name */
2, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_MANUAL_TRIG, /* equipment type */
0,
.......
}

the code fragment to manually trigger this event is:

int main(unsigned int argc,char **argv)
{
.......
bm_request_event(hBufEvent, 2, TRIGGER_ALL, GET_ALL, &request_id, process_event_TD);
.......
}

When it is time to save the data during the run, the function below is called:

BOOL trigger_histo_event(void)
{
HNDLE hconn;
BOOL event_triggered;
//
event_triggered = FALSE;
...................
if (run_state == STATE_RUNNING) { // Check the frontend client exists
if( cm_exist(ClientName,TRUE)) {
status = cm_connect_client (ClientName, &hconn);
if(status != RPC_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Cannot connect to frontend \"%s\" (%d)",
ClientName,status);
else { // successfully connected to frontend client
status = rpc_client_call(hconn, RPC_MANUAL_TRIG, 2); // trigger a histo event
if (status != CM_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Error triggering event from frontend (%d)",status);
else { // successfully triggered event
event_triggered=TRUE;
status =cm_disconnect_client(hconn, FALSE);
if (status != CM_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Error disconnecting client (%d)",status);
}
}
}
else
cm_msg(MERROR,"trigger_histo_event","Frontend client %s not running (%d)",
ClientName,status);
}
return(event_triggered);
}

==Deferred Transition==
This option permits the user to postpone any transition issued by any requester until some condition is satisfied.
For example:
* It may not be advisable to pause or stop a run until some hardware has turned off a particular valve.
* The start of the acquisition system should be postponed until the beam rate has been stable for a given period of time.
* While active, a particular acquisition system should not be interrupted until the "cycle" is completed.

In these examples, any application having access to the state of the hardware can register to be a "transition Deferred" client. The MIDAS system will then catch any transition request and postpone the trigger of such a transition until the condition is satisfied.

The Deferred transition requires 3 steps for setup
# Register for the deferred transition
# Provide a callback function to serve the deferred transition
# Implement the condition code

<b>Note that you should only have ONE frontend that defines a deferred transition</b> (as this niche feature that was implemented with this assumption in mind...).

The following example demonstrates this process:

BOOL transition_PS_requested=FALSE; // global
//
INT frontend_init()
{
// register for deferred transition
//
cm_register_deferred_transition(TR_STOP, wait_end_cycle);
cm_register_deferred_transition(TR_PAUSE, wait_end_cycle);
...
}
/*
*/
//-- Deferred transition callback
BOOL wait_end_cycle(int transition, BOOL first)
{
if (first) {
transition_PS_requested = TRUE;
return FALSE;
}
//
if (end_of_mcs_cycle){
transition_PS_requested = FALSE;
end_of_mcs_cycle = FALSE;
return TRUE;
}
else
return FALSE;
}
/*
*/
INT read_mcs_event(char *pevent, INT offset)
{
... // read out data at end of cycle
...
end_of_mcs_cycle = TRUE; // end of cycle
//
if (!transition_PS_requested)
start_cycle(); // start a new cycle
return bk_size(pevent);
}

In the example above,

* The frontend code is registered for PAUSE and STOP using ''cm_register_deferred_transition()''. The second argument ''wait_end_cycle'' is the declaration of the callback function.
* The callback function ''wait_end_cycle'' will be called as soon as the transition is requested with the Boolean flag ''first'' set to TRUE.
* By setting ''transition_PS_requested'' TRUE , the user will be provided with the acknowledgment of the transition request.
* By returning FALSE from the callback, the transition is prevented from occurring.
* As soon as the user condition is satisfied (''end_of_mcs_cycle'' = TRUE), the return code in the callback will be set to TRUE and the requested transition will be issued.

While the transition is Deferred, the odb key <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> will contain the transition code, and the d [[mhttpd]] webserver main status page will indicate that a deferred transition is in progress.

Once in deferred state, an [[odbedit]] override command can be issued to force the transition to happen,

>odbedit
odb> stop now (or "start now")

or <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> can be set to 0. The transition will then take place on the next stop or start command.

= Compilation using CMake =

Here is a "minimal" CMakeLists.txt file that can be used to compile a user-written frontend (called "myfe" in this case) that uses the mfe framework.

cmake_minimum_required(VERSION 3.14)
project(myfe)
find_package(Midas REQUIRED PATHS $ENV{MIDASSYS})
add_executable(myfe.exe myfe.cxx)
target_link_libraries(myfe.exe midas::mfe)

One could then build the executable using the following commands:

mkdir build
cd build
cmake ..
make

Some older operating systems may require the "cmake3" command to be used instead of "cmake".

In the above example we specify the midas::mfe target as we're building an mfe-based frontend. More targets are available for other types of midas client:

midas::midas - normal midas program
midas::midas-shared - normal midas programs using the shared midas library
midas::mfe - old style mfe.cxx frontend
midas::mfed - newer style frontend using mfed.cxx
midas::mscb - programs using MSCB system
midas::drivers - slow control program using any of the standard midas drivers

Note, the above only works for midas versions from January 2025 onwards. For earlier versions of midas, you need to be more explicit about midas' dependencies:

#
# Old version for pre-2025 versions of midas!
#

cmake_minimum_required(VERSION 3.0)
project(myfe)

# Check for MIDASSYS environment variable
if (NOT DEFINED ENV{MIDASSYS})
message(SEND_ERROR "MIDASSYS environment variable not defined.")
endif()

set(CMAKE_CXX_STANDARD 11)
set(MIDASSYS $ENV{MIDASSYS})

if (${CMAKE_SYSTEM_NAME} MATCHES Linux)
set(LIBS -lpthread -lutil -lrt)
endif()

# Define the executable to be built, and the source code files
add_executable(myfe.exe myfe.cxx)

# Directories to search for
target_include_directories(myfe.exe PRIVATE ${MIDASSYS}/include)

# Libraries to link to
target_link_libraries(myfe.exe ${MIDASSYS}/lib/libmfe.a ${MIDASSYS}/lib/libmidas.a ${LIBS})

= Using mfed to reduce the amount of boiler-plate code =

You can include <code>mfed.h</code> and compile against <code>mfed.cxx</code> to reduce the amount of boiler-plate code that needs to be written.

In particular:
* You only need to define the frontend_name and frontend_file_name [[#Global Declarations|globals]] (not display_period etc)
* You only need to declare your event readout functions (not the [[#System Function Declarations|system functions]])
* You still need to define your EQUIPMENT structs
* You need to define frontend_init(), from which you can call install_poll_event(), install_begin_of_run() etc to use your transition functions. If you don't need a pause_run() function, you don't need to declare/define it!
* It does not support interrupt routines

An example can be found in <code>$MIDASSYS/examples/experiment/frontend.cxx</code>.

The full list of functions you can call in your frontend_init() are:

; install_poll_event : Install a function which gets called to check if a new event is available for equipment of type EQ_POLLED.
; install_frontend_exit : Install a function which gets called when the frontend program finishes.
; install_begin_of_run : Install a function which gets called when a new run gets started.
; install_end_of_run : Install a function which gets called when a new run gets stopped.
; install_pause_run : Install a function which gets called when a new run gets paused.
; install_resume_run : Install a function which gets called when a new run gets resumed.
; install_frontend_loop : Install a function which gets called inside the main event loop as often as possible. This function gets all available CPU cycles, so in order not to take 100% CPU, this function can use the ss_sleep(10) function to give up some CPU cycles.

When compiling with cmake, your incantation for the executable would change:

# Without mfed (regular frontend):
add_executable(frontend frontend.cxx)

# With mfed:
add_executable(frontend frontend.cxx ${MIDASSYS}/src/mfed.cxx)

== Minimal example without mfed ==

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/* frontend_loop is called periodically if this variable is TRUE */
BOOL frontend_call_loop = TRUE;

/* a frontend status page is displayed with this frequency in ms */
INT display_period = 0000;

/* maximum event size produced by this frontend */
INT max_event_size = 10000;

/* maximum event size for fragmented events (EQ_FRAGMENTED) */
INT max_event_size_frag = 5 * 1024 * 1024;

/* buffer size to hold events */
INT event_buffer_size = 10 * 10000;

/*-- Function declarations -----------------------------------------*/

INT frontend_init();
INT frontend_exit();
INT begin_of_run(INT run_number, char *error);
INT end_of_run(INT run_number, char *error);
INT pause_run(INT run_number, char *error);
INT resume_run(INT run_number, char *error);
INT frontend_loop();
INT read_large_event(char *pevent, INT off);

/*-- Equipment list ------------------------------------------------*/

#undef USE_INT
BOOL equipment_common_overwrite = FALSE;

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

INT frontend_init()
{
return SUCCESS;
}

INT frontend_exit()
{
return SUCCESS;
}

INT begin_of_run(INT run_number, char *error)
{
return SUCCESS;
}

INT end_of_run(INT run_number, char *error)
{
return SUCCESS;
}

INT pause_run(INT run_number, char *error)
{
return SUCCESS;
}

INT resume_run(INT run_number, char *error)
{
return SUCCESS;
}

INT frontend_loop()
{
// Do something very frequently
return SUCCESS;
}

INT poll_event(INT source, INT count, BOOL test)
return 0;
}

INT interrupt_configure(INT cmd, INT source, PTYPE adr)
{
switch (cmd) {
case CMD_INTERRUPT_ENABLE:
break;
case CMD_INTERRUPT_DISABLE:
break;
case CMD_INTERRUPT_ATTACH:
break;
case CMD_INTERRUPT_DETACH:
break;
}
return SUCCESS;
}

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);
bk_close(pevent, pddata);

return bk_size(pevent);
}

== Minimal example with mfed ==

Note that you only need boiler-plate for the features you're actually going to use.

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/*-- Function declarations -----------------------------------------*/
INT frontend_init();
INT my_frontend_loop();
INT read_large_event(char *pevent, INT off);

/*-- Equipment list ------------------------------------------------*/

#undef USE_INT
BOOL equipment_common_overwrite = FALSE;

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

INT frontend_init()
{
install_frontend_loop(my_frontend_loop);

// Can also do install_begin_of_run() etc...

return SUCCESS;
}

INT my_frontend_loop()
{
// Do something frequently
return SUCCESS;
}

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);
bk_close(pevent, pddata);

return bk_size(pevent);
}

[[Category:Frontend]]

Frontend user code

2025-01-09T22:03:02Z

Bsmith: /* Compilation using CMake */

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Frontend Operation]]
* [[Frontend Application]]
* [[Equipment List Parameters]]
* [[Slow Control System]]
* [[Equipment Flags]]
* [[Event Notification (Hot-Link)]]
</div>

= Introduction =
This section describes the features of the user-written part of a "C-style" [[Frontend Operation#Frontend|Frontend]], referred to here as '''frontend.c'''.

You can also write frontends using [[Frontend_user_code_(object_oriented_-_TMFE)|object-oriented C++ (TMFE)]] or [[Python]].

The frontend system has evolved over the decades, and contains some legacy features that are not often used (e.g. interrupt handlers). For backwards-compatibility, these features are still present, but this does require a bit more boiler-plate code to be written for each frontend. We will first document every feature supported by the frontend system, then explain a slightly more user-friendly wrapper (mfed.cxx) that helps reduce the amount of boiler-plate needed for a new frontend.

= Frontend Templates =
To make a user-written or custom frontend, users will usually modify one of the '''templates''' provided in the MIDAS package
under [[Environment Variables#MIDASSYS|$MIDASSYS]]/examples/ for their particular hardware and other requirements. Make sure to pick the closest template, e.g. if writing a [[Slow Control System|Slow Control]] frontend, pick a slow-control template. For each example frontend, a Makefile is also provided.

A partial list of the templates provided is shown below:
{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="3" cellpadding="2" cellspacing="2"

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Hardware
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Filename
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Directory (MIDAS package)
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Purpose
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Language

|-
|VME
|fevmemodules.c
| $MIDASSYS/examples/Triumf/c/
| Access to VME modules
| C

|-
|VME
|fevme.cxx
| $MIDASSYS/examples/Triumf/c++/
| Access to VME modules
| C++

|-
|CAMAC
|frontend.c
| $MIDASSYS/examples/experiment/
| Access to CAMAC modules
| C

|-
|
|mtfe.c
| $MIDASSYS/examples/mtfe/
| '''Multithreaded''' using ring buffer
| C

|-
| Wiener CC-USB
|feccusb.cxx
| $MIDASSYS/examples/mtfe/
| CAMAC/USB demo
| C++

|-
|RS485 bus
|mscb_fe.c
| $MIDASSYS/examples/slowcont/
| '''Slow control''' with [https://midas.psi.ch/mscb/ MSCB]
| C

|-
|EPICS
|frontend.c
| $MIDASSYS/examples/epics/
| '''Slow controls'''
| C

|-
|Camac
|ebfe.c
| $MIDASSYS/examples/eventbuilder/
| '''Event Builder''' (with [[mevb]])
| C

|-
|
|frontend.cxx
| $MIDASSYS/examples/experiment/
| '''mfed''' (wrapper to simplify writing a frontend)
| C++

|}

The features of a typical frontend program are best explained by reference to examples of the user code
provided in the Midas Package.

=Frontend code=
Note that there are several kinds of frontend used for different purposes, e.g.
* frontend to read VME or CAMAC hardware, using interrupt or polling (e.g. to read experimental data)
* multithreaded frontend where polling can be in a separate thread
* slow control frontend (can be multithreaded) see also [[Slow Control System]]
* etc.

Templates for many types of user frontend code are provided in the MIDAS packages (see [[#Frontend Templates]]).

The following sections refer to these templates.
Most of the examples are taken from the [https://bitbucket.org/tmidas/midas/src/develop/examples/basic/largefe.cxx largefe.cxx example]. Documentation on the MIDAS library subroutines to access the ODB (some of which are used in the examples below) can be found in the [[ODB_Access_and_Use|ODB access page]].

The user frontend code is then compiled and linked with the system part and the MIDAS library
(see [[Frontend Operation#Frontend|Frontend Task]]). Makefiles are provided with the templates that can be modified as needed.

== Access to command line parameters ==
The function '''mfe_get_args''' gives access to the [[Frontend Application|Frontend]] command line parameters.

This example shows how to use it in the frontend user code:

int argc;
char **argv;
mfe_get_args(&argc, &argv);
for (int i = 0; i < argc; i++) {
// Use argv[i]
}

See [[Frontend_Application#Arguments|Frontend Application Arguments]] for the arguments that are handled automatically by the frontend system.

==Include files==
The following example (from template frontend file ''$MIDASSYS/examples/basic/largefe.cxx'') shows the standard include files needed for a frontend. The user may add any other include files as needed (e.g. those needed for VME access).

Some legacy frontends may include the '''[[ODB#experim.h include file|experim.h]]''' file. This was an old way of accessing the ODB, but was not very user-friendly when the ODB structure needed to change.

The example below shows a typical list of include files for a frontend:

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

'''<div id="Frontend Name"></div>'''
==Global Declarations==
The following example (from template frontend file fevmemodules.c - see [[#Frontend Templates]]) shows the global declaration. The declarations are system wide. Some may be changed to suit the user, but none should not be removed.

; frontend_name : This value can be modified to reflect the purpose of the code
; frontend_call_loop : If set to TRUE, the function frontend_loop() gets called very frequently. If FALSE, frontend_loop() does not run. The user can add suitable code to this routine if desired (e.g. to check for a condition).
; display_period : The time interval (defined in milliseconds) between the refresh of a frontend status display. The value of zero disables the display. If the frontend is started in the background with the display enabled, the stdout should be redirected to the null device to prevent the process from hanging.
; max_event_size : specifies the maximum size (in bytes) of the expected event.
; event_buffer_size : specifies the maximum size (in bytes) of the buffer to be allocated by the system.
; equipment_common_overwrite : whether the definitions in the EQUIPMENT struct override those in the /Equipment/largefe/Common section of the ODB. If FALSE, the values in the struct will be used the first time the program runs, then the ODB values will be used afterwards (e.g. allowing you to change the period of a [[#Event_Types_and_Triggers|periodic equipment]] via the ODB).

See below for an example of global declarations from a frontend.

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/* frontend_loop is called periodically if this variable is TRUE */
BOOL frontend_call_loop = TRUE;

/* a frontend status page is displayed with this frequency in ms */
INT display_period = 0;

/* maximum event size produced by this frontend */
INT max_event_size = 10000;

/* maximum event size for fragmented events (EQ_FRAGMENTED) */
INT max_event_size_frag = 5 * 1024 * 1024;

/* buffer size to hold events */
INT event_buffer_size = 10 * 10000;

/* whether the values in EQUIPMENT struct override ODB values */
BOOL equipment_common_overwrite = FALSE;

==System Function Declarations==

These lines declare the pre-defined system functions which should be present.

INT frontend_init();
INT frontend_exit();
INT begin_of_run(INT run_number, char *error);
INT end_of_run(INT run_number, char *error);
INT pause_run(INT run_number, char *error);
INT resume_run(INT run_number, char *error);
INT frontend_loop();

==Readout Function Declarations==
Following the previous group is a second group of declarations, which define the readout functions. These depend on the defined equipments, and run when the respective equipment is triggered. In this example, one equipment will be defined, so there is one declaration. The user functions will be described in detail in later sections.

INT read_large_event(char *pevent, INT off);

If using an interrupt, callback function prototypes are also included

extern void interrupt_routine(void);
void register_cnaf_callback(int debug);

==Equipment List==

This list of structs defines the behaviour of your frontend (e.g. [[#Event_Types_and_Triggers|periodic or polled equipment]]). See [[Equipment List Parameters|Equipment List]] for full documentation of the entries.

Note that these are the default values for each equipment (used the very first time a frontend is run). If [[#Global declarations|equipment_common_overwrite]] is FALSE, then some of the values will subsequently be read from the ODB instead. If [[#Global declarations|equipment_common_overwrite]] is TRUE, then the ODB will be updated with the coded values each time the program runs.

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

In the case of a polled equipment, the struct would be of the form:

EQUIPMENT equipment[] = {
{ "Trigger", // equipment name
{
...
<b>EQ_POLLED</b>, // equipment type
...
500, // poll for 500ms
...
"", "", "",},
read_my_event, // readout routine
...

In the case of a periodic equipment, the struct would be of the form:

EQUIPMENT equipment[] = {
{ "Scaler", // equipment name
{
...
EQ_PERIODIC // equipment type
...
10000, // period (read every 10s)
...
"", "", "",},
read_my_event, // readout routine
...

==Sequence of Operations in the frontend==

The following table shows the sequence of operations of the [[Frontend Operation#Frontend|Frontend]] System functions. These functions must be implemented in the user's code (but may be as simple as just returning <code>SUCCESS</code> if the function is not relevant for your use case). These functions are called by ''mfe.cxx'' at the appropriate time. The System Transition functions are associated with a particular [[Run States and Transitions|Run Transition]] as shown below:

{| style="text-align: left; width: 60%; background-color: rgb(255, 255, 255);" border="0" cellpadding="2" cellspacing="2"

|-
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | System Function
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | System Transition Function
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Associated [[Run States and Transitions|Transition]]
| colspan="1" rowspan="1" style="vertical-align: top; background-color: rgb(255, 255, 204); font-weight: bold;" | Action

|-
| frontend_init()
|
|
| Runs once after system initialization, before Equipment registration.

|-
|
| begin_of_run()
| style="color:blue"|TR_START
| Runs after system statistics reset at each begin-of-run request.

|-
|
| pause_run()
| style="color:blue"|TR_PAUSE
| Runs at each pause-run request.

|-
|
| resume_run()
| style="color:blue"|TR_RESUME
| Runs at each resume-run request.

|-
|
| end_of_run()
| style="color:blue"|TR_STOP
| Runs at each end-of-run request.

|-
| frontend_exit()
|
|
| Runs once before any Slow Control Equipment exit
|}

Each defined Equipment has the option to force itself to run at individual transition times (see Equipment [[Equipment List Parameters#ReadOn|ReadOn Flag]]), so that its equipment function will be called on a certain transition (or combination of transitions).

The system transition functions all run '''prior to''' the equipment functions. This gives the system the chance to take basic action on the transition request (e.g. enable/disable interrupt) before the equipment runs. All the transition routines run with a [[Run States and Transitions#Default Transition Sequency Numbers|Transition Sequence number]] of 500 (the default). This allows users to add additional functions in the frontend that will run before or after any of the transitions (such as a prestart() or a poststop() function). See [[Run States and Transitions#Run Transition Priority|Run Transition Priority]] for more information.

==Function frontend_init ==

No parameters.

This function runs '''once only''' at the application startup. Users may perform hardware checking, loading/setting of global variables, mapping of required ODB structures (see [[ODB#experim.h include file|experim.h include file]]),
[[Event Notification (Hot-Link)#How to set up a Hot-Link|setting up hot-links]] etc. in frontend_init(), e.g.

INT frontend_init()
{
set_equipment_status(equipment[0].name, "Initializing...", "yellow");
....
set_equipment_status(equipment[0].name, "OK", "green");

return SUCCESS;
}

===Reporting Equipment Status===
If running with the webserver [[mhttpd]], a frontend can send an update to the [[Status Page]], to report on its progress, using the function set_equipment_status() (see above example). This is useful when hardware can take a long time to respond.

==Function begin_of_run==

Parameters:
* INT '''run number''' provides the number of the current run being started
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

This function is called every time a run start transition occurs, i.e. at begin-of-run. It allows the updating of user parameters, and the loading/setup/clearing of hardware. At the exit of this function, the acquisition should be armed and ready to test the interrupt (if used), e.g.

INT begin_of_run (INT runnumber, char * error)
{
// Read/validate some settings from the ODB (and return FE_ERR_ODB if there's a problem).
// Apply them to the hardware (and return FE_ERR_HW if there's a problem).
// etc...
return SUCCESS;
}

==Functions pause/resume_run==

Parameters:
* INT '''run number''' provides the number of the current run being paused/resumed.
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

These two functions are called upon "Pause" and "Resume" command respectively. Any code relevant to the upcoming run state can be included,e.g.

INT pause_run (INT run_number, char * error)
{
disable_trigger();
// Disable interrupt
inRun = 0;
mvme_write_value(myvme, VLAM_BASE+4, inRun);
return SUCCESS;
}
//
INT resume_run (INT run_number, char * error)
{
enable_trigger();
inRun = 1;
mvme_write_value(myvme, VLAM_BASE+4, inRun);
return SUCCESS;
}

==Function end_run==

Parameters:
* INT '''run number''' provides the number of the current run being ended.
* char * '''error''' can be used for returning a message to the system. This message string will be logged into the ''midas.log'' file (see [[Message System]].

This function is called at every "stop run" transition. It provides the opportunity to disable the hardware, e.g.

INT end_of_run(INT run_number, char *error)
{
// Stop the hardware.
// etc...
return SUCCESS;
}

==Function frontend_exit==

Parameters: none

The function runs when the frontend program is shut down. Can be used to release any locked resources like memory, communications ports etc. e.g.

function frontend_exit()
{
mvme_close(gVme);
return;
}

==Function frontend_loop==

Parameters: none

If [[#Global declarations|frontend_call_loop]] is set to TRUE, this routine is called when the frontend is idle and at least once between every event. You could use it for example to check if there has been a timeout from hardware.

...
BOOL frontend_call_loop = TRUE;
...

INT frontend_loop()
{
// Implement any code that needs to be run very frequently
return SUCCESS;
}

==Event Types and Triggers==
The frontend supports several different types of [[Frontend Operation#Frontend event triggers|event trigger]]. The event trigger type is specified by the [[Equipment Flags|Equipment Flag]] in the [[Equipment List Parameters|Equipment Declaration]]. Common event types are "polled events" where the Equipment Flag is [[Equipment Flags#EQ_POLLED|EQ_POLLED]], "interrupts events" where the Flag is [[Equipment Flags#EQ_INTERRUPT|EQ_INTERRUPT]], and "periodic events" where the Flag is [[Equipment Flags#EQ_PERIODIC|EQ_PERIODIC]]. The name of the associated readout routine is specified in the [[Equipment List Parameters|Equipment Declaration]] for each event type.

Polled and interrupt events (see [[#Event Types|Event Types]]) require several extra functions to handle the hardware that periodic events do not require. These are described below.

Note that each frontend may contain:
* zero or one polled equipments
* zero or one interrupt equipments
* any number of periodic equipments

==Function poll_event==
Parameters:
* INT '''source'''
* INT '''count'''
* BOOL '''test'''

If the [[Equipment List Parameters#Equipment Type|Equipment Type]] is EQ_POLLED, the poll_event() routine will be called as often as possible over the corresponding poll time (e.g. 500ms) given by each polling equipment.

The user must provide suitable code in the routine poll_event(), e.g. reading a register from a VME module to see if any data is available

INT poll_event(INT source, INT count, BOOL test)
{
/* Polling routine for events. Returns TRUE if event is available. If test equals TRUE, don't return.
The test flag is used to time the polling
*/
int i;
int lam = 0;
//
for (i = 0; i < count; i++, lam++) {
lam = vmeio_CsrRead(myvme, VMEIO_BASE);
if (lam)
if (!test)
return lam;
}
return 0;
}

An [[#Event Readout routine|event readout routine]] must also be provided by the user.

==Function interrupt_configure==
* INT '''cmd'''
* INT '''source'''
* PTYPE '''adr'''

If the [[Equipment List Parameters#Equipment Type|Equipment Type]] is EQ_INTERRUPT, an interrupt configuration routine called interrupt_configure() must be provided by the user.
The interrupt configuration routine has the following declaration:

/*-- Interrupt configuration --------------------------*/
INT interrupt_configure(INT cmd, INT source, PTYPE adr)
{
int vec = 0;
switch (cmd)
{
case CMD_INTERRUPT_ENABLE:
if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x1);
break;
//
case CMD_INTERRUPT_DISABLE:
if (inRun) mvme_write_value(myvme, VLAM_BASE+4, 0x0);
break;
//
case CMD_INTERRUPT_ATTACH:
mvme_set_dmode(myvme, MVME_DMODE_D32);
mvme_interrupt_attach(myvme, INT_LEVEL, INT_VECTOR,
(void *)adr, &myinfo);
mvme_write_value(myvme, VLAM_BASE+0x10, INT_VECTOR);
vec = mvme_read_value(myvme, VLAM_BASE+0x10);
printf("Interrupt Attached to 0x%x for vector:0x%x\n",
adr, vec&0xFF);
break;
//
case CMD_INTERRUPT_DETACH:
printf("Interrupt Detach\n");
break;
}
return SUCCESS;
}

Under the four commands listed above, the user must implement the hardware operation needed to perform the requested action. In the Midas drivers directory examples can be found of such an interrupt code for CAMAC. See source code such as hyt1331.c,ces8210.c

An [[#Event Readout routine|event readout routine]] must also be provided by the user in the frontend.

==Event Readout routine==

An event readout routine is required for all equipment, and is responsible for sending the actual data to midas. The framework calls the event readout routine whenever an equipment has been triggered (e.g. periodicially, or because poll_event() returned TRUE for a polled equipment etc). The function is of the form

INT function_name ( char *pevent ... )
{
INT event_size;
........ // read data from hardware
........ // pack into banks depending on format
........
return (event_size);
}

where the first argument of the readout function (pevent) provides the pointer to the newly constructed event, and points to the first valid location for storing the data.
;NOTE
* <b>The return value is the event size</b>, and must be the number of bytes collected in this function. This is different to almost every other function in midas (where the return value is a status code).
* You can return 0 if you've decided you don't actually want to write this event.
* The event serial number will be incremented by one for every call to the readout routine, as long as the returned size is non-zero.

===General readout function===

A readout function is needed to send out data. This is done using one of the supported [[Event Structure|event structures]] usually [[Event Structure#MIDAS Format Event|"MIDAS" format]] data banks. The bank format ("MIDAS" in the example above) is declared in the [[Equipment List Parameters]] [[Equipment List Parameters#Format|Format]] field.

An example of a scaler readout routine read_scaler_event() where the data is read out into [[MIDAS Event Construction|MIDAS data banks]] is shown below.

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

/* create bank (bank names must be 4 chars long) */
bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);

/* fill data (just dummy values in this case) */
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);

/* close the bank */
bk_close(pevent, pddata);

/* return the number of bytes we wrote */
return bk_size(pevent);
}

Some other examples of event readout routines in this document are
* [[Event Structure#FIXED Event Construction|FIXED Format event construction]]
* [[Super Event]] construction
* [[Slow Control System|Slow Control]]

Many other examples of readout routines can be found in the [[#Frontend Templates|frontend templates]] in the MIDAS package.

===Polled or Interrupt readout routine===
In the case of a [[#Polled and Interrupt Events|Polled or Interrupt event]], the content of the memory location pointed to by '''pevent''' (see [[#Event Readout routine|Event Readout routine]]) prior to its use in the readout function, contains the interrupt source bitwise register. This feature can be exploited in order to identify which hardware module has triggered the readout when multiple interrupts have been assigned to the same readout function.

The examples below show a VME interrupt source for a given equipment. Depending whether USE_INT is defined, the Equipment will either use a Polled or an Interrupt mechanism.
The [[Equipment List Parameters|Equipment declaration]] is of the form:

EQUIPMENT equipment[] = {
//
{"Trigger", /* equipment name */
...
#ifdef USE_INT
EQ_INTERRUPT, /* equipment type */
#else
EQ_POLLED, /* equipment type */
#endif
/* interrupt source: crate 0, all stations */
LAM_SOURCE(0, 0x0),
....
"", "", "",
},
read_trigger_event, /* readout routine */
NULL, NULL,
trigger_bank_list,
}

Note that the [[Macros#CAMAC Macros|LAM_SOURCE macro]] simply codes the parameters into a bitwise register.

The readout routine would contains code such as

INT read_trigger_event(char *pevent, INT off)
{
#if defined VADC0_CODE
DWORD *pdata;
#endif
//
#if defined VADC0_CODE
/* read ADC0 data */
v792_EvtCntRead(myvme, VADC0_BASE, &evtcnt);
........
/* Read Event */
v792_EventRead(myvme, VADC0_BASE, pdata, &nentry);
........
v792_DataClear(myvme, VADC0_BASE);
#endif
//
........
return (size);
}

The data will be packed into banks as described for the [[General readout function|general readout function]] above.
The example <code>$MIDASSYS/examples/Triumf/c/fevmemodules.c</code> contains a complete example of read_trigger_event().

==Manual Trigger==
Another type of [[Frontend Operation#Frontend event trigger|frontend event trigger]] supported is the "manual trigger", where the Equipment Flag is [[Equipment Flags#EQ_MANUAL_TRIGGER|EQ_MANUAL_TRIGGER]]. This flag means that an event can be triggered through the URL <code>?cmd=Trigger/<equipment_name></code> (e.g. <code>http://my.host:8080/?cmd=Trigger/MyEquipmentName</code>). If you add this URL to the [[/Alias ODB tree|/Alias]] part of the ODB, then a link will appear on midas webpages that can be clicked to trigger an event.

In some cases, the same readout code may be used for two types of event: a manual trigger and (say) a poll event. It is possible to determine whether the readout of an event was triggered by a manual trigger or a regular trigger by adding a call to the [[MIDAS Event Header Macros|event header Macro]] DATA_SIZE in the readout routine:

flag = DATA_SIZE(pevent);

If the result is
* flag = 0 normal call
* flag = 1 manual trigger

It is also possible for a backend MIDAS client (such as an analyzer or custom data archiver) to trigger a manual trigger event. The client controls when an event is sent by means of
a function that requests an event by triggering the event sending mechanism with a RPC call.

With a frontend Equipment declaration of a manually triggered event of the form:

{ "Histo", /* equipment name */
2, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_MANUAL_TRIG, /* equipment type */
0,
.......
}

the code fragment to manually trigger this event is:

int main(unsigned int argc,char **argv)
{
.......
bm_request_event(hBufEvent, 2, TRIGGER_ALL, GET_ALL, &request_id, process_event_TD);
.......
}

When it is time to save the data during the run, the function below is called:

BOOL trigger_histo_event(void)
{
HNDLE hconn;
BOOL event_triggered;
//
event_triggered = FALSE;
...................
if (run_state == STATE_RUNNING) { // Check the frontend client exists
if( cm_exist(ClientName,TRUE)) {
status = cm_connect_client (ClientName, &hconn);
if(status != RPC_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Cannot connect to frontend \"%s\" (%d)",
ClientName,status);
else { // successfully connected to frontend client
status = rpc_client_call(hconn, RPC_MANUAL_TRIG, 2); // trigger a histo event
if (status != CM_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Error triggering event from frontend (%d)",status);
else { // successfully triggered event
event_triggered=TRUE;
status =cm_disconnect_client(hconn, FALSE);
if (status != CM_SUCCESS)
cm_msg(MERROR,"trigger_histo_event","Error disconnecting client (%d)",status);
}
}
}
else
cm_msg(MERROR,"trigger_histo_event","Frontend client %s not running (%d)",
ClientName,status);
}
return(event_triggered);
}

==Deferred Transition==
This option permits the user to postpone any transition issued by any requester until some condition is satisfied.
For example:
* It may not be advisable to pause or stop a run until some hardware has turned off a particular valve.
* The start of the acquisition system should be postponed until the beam rate has been stable for a given period of time.
* While active, a particular acquisition system should not be interrupted until the "cycle" is completed.

In these examples, any application having access to the state of the hardware can register to be a "transition Deferred" client. The MIDAS system will then catch any transition request and postpone the trigger of such a transition until the condition is satisfied.

The Deferred transition requires 3 steps for setup
# Register for the deferred transition
# Provide a callback function to serve the deferred transition
# Implement the condition code

<b>Note that you should only have ONE frontend that defines a deferred transition</b> (as this niche feature that was implemented with this assumption in mind...).

The following example demonstrates this process:

BOOL transition_PS_requested=FALSE; // global
//
INT frontend_init()
{
// register for deferred transition
//
cm_register_deferred_transition(TR_STOP, wait_end_cycle);
cm_register_deferred_transition(TR_PAUSE, wait_end_cycle);
...
}
/*
*/
//-- Deferred transition callback
BOOL wait_end_cycle(int transition, BOOL first)
{
if (first) {
transition_PS_requested = TRUE;
return FALSE;
}
//
if (end_of_mcs_cycle){
transition_PS_requested = FALSE;
end_of_mcs_cycle = FALSE;
return TRUE;
}
else
return FALSE;
}
/*
*/
INT read_mcs_event(char *pevent, INT offset)
{
... // read out data at end of cycle
...
end_of_mcs_cycle = TRUE; // end of cycle
//
if (!transition_PS_requested)
start_cycle(); // start a new cycle
return bk_size(pevent);
}

In the example above,

* The frontend code is registered for PAUSE and STOP using ''cm_register_deferred_transition()''. The second argument ''wait_end_cycle'' is the declaration of the callback function.
* The callback function ''wait_end_cycle'' will be called as soon as the transition is requested with the Boolean flag ''first'' set to TRUE.
* By setting ''transition_PS_requested'' TRUE , the user will be provided with the acknowledgment of the transition request.
* By returning FALSE from the callback, the transition is prevented from occurring.
* As soon as the user condition is satisfied (''end_of_mcs_cycle'' = TRUE), the return code in the callback will be set to TRUE and the requested transition will be issued.

While the transition is Deferred, the odb key <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> will contain the transition code, and the d [[mhttpd]] webserver main status page will indicate that a deferred transition is in progress.

Once in deferred state, an [[odbedit]] override command can be issued to force the transition to happen,

>odbedit
odb> stop now (or "start now")

or <span style="color: purple; font-style:italic;">/runinfo/Requested transition</span> can be set to 0. The transition will then take place on the next stop or start command.

= Compilation using CMake =

Here is a "minimal" CMakeLists.txt file that can be used to compile a user-written frontend (called "myfe" in this case) that uses the mfe framework.

cmake_minimum_required(VERSION 3.10)
project(myfe)
find_package(Midas REQUIRED PATHS $ENV{MIDASSYS})
add_executable(myfe.exe myfe.cxx)
target_link_libraries(myfe.exe midas::mfe)

One could then build the executable using the following commands:

mkdir build
cd build
cmake ..
make

Some older operating systems may require the "cmake3" command to be used instead of "cmake".

In the above example we specify the midas::mfe target as we're building an mfe-based frontend. More targets are available for other types of midas client:

midas::midas - normal midas program
midas::midas-shared - normal midas programs using the shared midas library
midas::mfe - old style mfe.cxx frontend
midas::mfed - newer style frontend using mfed.cxx
midas::mscb - programs using MSCB system
midas::drivers - slow control program using any of the standard midas drivers

Note, the above only works for midas versions from January 2025 onwards. For earlier versions of midas, you need to be more explicit about midas' dependencies:

#
# Old version for pre-2025 versions of midas!
#

cmake_minimum_required(VERSION 3.0)
project(myfe)

# Check for MIDASSYS environment variable
if (NOT DEFINED ENV{MIDASSYS})
message(SEND_ERROR "MIDASSYS environment variable not defined.")
endif()

set(CMAKE_CXX_STANDARD 11)
set(MIDASSYS $ENV{MIDASSYS})

if (${CMAKE_SYSTEM_NAME} MATCHES Linux)
set(LIBS -lpthread -lutil -lrt)
endif()

# Define the executable to be built, and the source code files
add_executable(myfe.exe myfe.cxx)

# Directories to search for
target_include_directories(myfe.exe PRIVATE ${MIDASSYS}/include)

# Libraries to link to
target_link_libraries(myfe.exe ${MIDASSYS}/lib/libmfe.a ${MIDASSYS}/lib/libmidas.a ${LIBS})

= Using mfed to reduce the amount of boiler-plate code =

You can include <code>mfed.h</code> and compile against <code>mfed.cxx</code> to reduce the amount of boiler-plate code that needs to be written.

In particular:
* You only need to define the frontend_name and frontend_file_name [[#Global Declarations|globals]] (not display_period etc)
* You only need to declare your event readout functions (not the [[#System Function Declarations|system functions]])
* You still need to define your EQUIPMENT structs
* You need to define frontend_init(), from which you can call install_poll_event(), install_begin_of_run() etc to use your transition functions. If you don't need a pause_run() function, you don't need to declare/define it!
* It does not support interrupt routines

An example can be found in <code>$MIDASSYS/examples/experiment/frontend.cxx</code>.

The full list of functions you can call in your frontend_init() are:

; install_poll_event : Install a function which gets called to check if a new event is available for equipment of type EQ_POLLED.
; install_frontend_exit : Install a function which gets called when the frontend program finishes.
; install_begin_of_run : Install a function which gets called when a new run gets started.
; install_end_of_run : Install a function which gets called when a new run gets stopped.
; install_pause_run : Install a function which gets called when a new run gets paused.
; install_resume_run : Install a function which gets called when a new run gets resumed.
; install_frontend_loop : Install a function which gets called inside the main event loop as often as possible. This function gets all available CPU cycles, so in order not to take 100% CPU, this function can use the ss_sleep(10) function to give up some CPU cycles.

When compiling with cmake, your incantation for the executable would change:

# Without mfed (regular frontend):
add_executable(frontend frontend.cxx)

# With mfed:
add_executable(frontend frontend.cxx ${MIDASSYS}/src/mfed.cxx)

== Minimal example without mfed ==

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/* frontend_loop is called periodically if this variable is TRUE */
BOOL frontend_call_loop = TRUE;

/* a frontend status page is displayed with this frequency in ms */
INT display_period = 0000;

/* maximum event size produced by this frontend */
INT max_event_size = 10000;

/* maximum event size for fragmented events (EQ_FRAGMENTED) */
INT max_event_size_frag = 5 * 1024 * 1024;

/* buffer size to hold events */
INT event_buffer_size = 10 * 10000;

/*-- Function declarations -----------------------------------------*/

INT frontend_init();
INT frontend_exit();
INT begin_of_run(INT run_number, char *error);
INT end_of_run(INT run_number, char *error);
INT pause_run(INT run_number, char *error);
INT resume_run(INT run_number, char *error);
INT frontend_loop();
INT read_large_event(char *pevent, INT off);

/*-- Equipment list ------------------------------------------------*/

#undef USE_INT
BOOL equipment_common_overwrite = FALSE;

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

INT frontend_init()
{
return SUCCESS;
}

INT frontend_exit()
{
return SUCCESS;
}

INT begin_of_run(INT run_number, char *error)
{
return SUCCESS;
}

INT end_of_run(INT run_number, char *error)
{
return SUCCESS;
}

INT pause_run(INT run_number, char *error)
{
return SUCCESS;
}

INT resume_run(INT run_number, char *error)
{
return SUCCESS;
}

INT frontend_loop()
{
// Do something very frequently
return SUCCESS;
}

INT poll_event(INT source, INT count, BOOL test)
return 0;
}

INT interrupt_configure(INT cmd, INT source, PTYPE adr)
{
switch (cmd) {
case CMD_INTERRUPT_ENABLE:
break;
case CMD_INTERRUPT_DISABLE:
break;
case CMD_INTERRUPT_ATTACH:
break;
case CMD_INTERRUPT_DETACH:
break;
}
return SUCCESS;
}

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);
bk_close(pevent, pddata);

return bk_size(pevent);
}

== Minimal example with mfed ==

Note that you only need boiler-plate for the features you're actually going to use.

#include <stdio.h>
#include <stdlib.h>
#include "midas.h"
#include "mfe.h"

/*-- Globals -------------------------------------------------------*/
/* The frontend name (client name) as seen by other MIDAS clients */
const char *frontend_name = "largefe";

/* The frontend file name, don't change it */
const char *frontend_file_name = __FILE__;

/*-- Function declarations -----------------------------------------*/
INT frontend_init();
INT my_frontend_loop();
INT read_large_event(char *pevent, INT off);

/*-- Equipment list ------------------------------------------------*/

#undef USE_INT
BOOL equipment_common_overwrite = FALSE;

EQUIPMENT equipment[] = {

{"large", /* equipment name */
{3, 0, /* event ID, trigger mask */
"SYSTEM", /* event buffer */
EQ_PERIODIC | EQ_FRAGMENTED, /* equipment type */
0, /* event source */
"MIDAS", /* format */
TRUE, /* enabled */
RO_ALWAYS, /* read when running and on transitions */
2000, /* read every 2 sec */
0, /* stop run after this event limit */
0, /* number of sub events */
0, /* log history */
"", "", ""},
read_large_event, /* readout routine */
NULL, NULL, /* keep null */
NULL, /* init string */
},

{""}
};

INT frontend_init()
{
install_frontend_loop(my_frontend_loop);

// Can also do install_begin_of_run() etc...

return SUCCESS;
}

INT my_frontend_loop()
{
// Do something frequently
return SUCCESS;
}

INT read_large_event(char *pevent, INT off)
{
DWORD *pddata;

/* init bank structure */
bk_init32(pevent);

bk_create(pevent, "BIGG", TID_DWORD, (void **) &pddata);
memset((char *) pddata, 0x0000, 100);
pddata += 1000000;
memset((char *) pddata - 100, 0xFFFF, 100);
bk_close(pevent, pddata);

return bk_size(pevent);
}

[[Category:Frontend]]

/Alarms ODB tree

2025-01-07T20:04:58Z

Bsmith: Alarm sound and trigger count

{{Pagelinks}}

= Links =
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* [[Alarms Page]]
* [[Alarm System]]
* [[Mhttpd|mhttpd MIDAS web server]]
* [[odbedit]]
</div>
= Purpose =
The ODB /Alarms tree contains user and system information related to alarms (see [[Alarm System]]). The information from this tree is displayed in the [[Alarms Page]].

= Creating the /Alarms tree =
When the ODB is created, the /Alarms tree is automatically created, with
* two Alarms with [[#<alarm-name> subtree|<alarm name>]] "Demo ODB" and "Demo periodic" and
* two Classes with [[#<class-name> subtree|<class name>]] "Alarm" and "Warning".

These are shown in the [[#Example of an /Alarms tree|example below]].

The user may create other alarms and classes by copying an existing <alarm-name> or <alarm-class> subtree and editing (via [[Alarms Page]] or [[odbedit]]) as required.

By default, the [[Alarm System]] is NOT active. When it is active,
the overall alarm is checked once every minute. Once the alarm has been triggered, the message associated with the alarm can be repeated at a different rate.

= Example =
This example (using [[odbedit]]) shows the default <span style="color: purple; font-style:italic;">/Alarms</span> tree. See also [[Alarms Page]].

$ odbedit
[local:pol:S]/>cd /alarms
[local:pol:S]/Alarms>ls
Alarm system active y
Alarms
Classes

[local:pol:S]/Alarms>ls -r -lt
Key name Type #Val Size Last Opn Mode Value
---------------------------------------------------------------------------
Alarms DIR
Alarm system active BOOL 1 4 4h 0 RWD y
Alarms DIR
Demo ODB DIR
Active BOOL 1 4 >99d 0 RWD n
Triggered INT 1 4 >99d 0 RWD 0
Type INT 1 4 >99d 0 RWD 3
Check interval INT 1 4 >99d 0 RWD 60
Checked last DWORD 1 4 >99d 0 RWD 0
Trigger count DWORD 1 4 >99d 0 RWD 0
Trigger count requirDWORD 1 4 >99d 0 RWD 0
Time triggered firstSTRING 1 32 >99d 0 RWD
Time triggered last STRING 1 32 >99d 0 RWD
Condition STRING 1 256 >99d 0 RWD /Runinfo/Run number > 100
Alarm Class STRING 1 32 >99d 0 RWD Alarm
Alarm Message STRING 1 80 >99d 0 RWD Run number became too large
Demo periodic DIR
Active BOOL 1 4 >99d 0 RWD n
Triggered INT 1 4 >99d 0 RWD 0
Type INT 1 4 >99d 0 RWD 4
Check interval INT 1 4 >99d 0 RWD 28800
Checked last DWORD 1 4 >99d 0 RWD 1058817867
Trigger count DWORD 1 4 >99d 0 RWD 0
Trigger count requirDWORD 1 4 >99d 0 RWD 0
Time triggered firstSTRING 1 32 >99d 0 RWD
Time triggered last STRING 1 32 >99d 0 RWD
Condition STRING 1 256 >99d 0 RWD
Alarm Class STRING 1 32 >99d 0 RWD Warning
Alarm Message STRING 1 80 >99d 0 RWD Please do your shift checks
fePOL DIR
Active BOOL 1 4 19s 0 RWD y
Triggered INT 1 4 19s 0 RWD 205
Type INT 1 4 3s 0 RWD 2
Check interval INT 1 4 19s 0 RWD 60
Checked last DWORD 1 4 19s 0 RWD 1259196026
Trigger count DWORD 1 4 >99d 0 RWD 0
Trigger count requirDWORD 1 4 >99d 0 RWD 0
Time triggered firstSTRING 1 32 19s 0 RWD Wed Nov 25 12:59:33 2009
Time triggered last STRING 1 32 19s 0 RWD Wed Nov 25 16:40:26 2009
Condition STRING 1 256 3s 0 RWD Program not running
Alarm Class STRING 1 32 19s 0 RWD Caution
Alarm Message STRING 1 80 19s 0 RWD Program fePOL is not running
Classes DIR
Alarm DIR
Write system messageBOOL 1 4 27h 0 RWD y
Write Elog message BOOL 1 4 27h 0 RWD n
System message interINT 1 4 27h 0 RWD 60
System message last DWORD 1 4 27h 0 RWD 0
Execute command STRING 1 256 27h 0 RWD
Execute interval INT 1 4 27h 0 RWD 0
Execute last DWORD 1 4 27h 0 RWD 0
Stop run BOOL 1 4 27h 0 RWD n
Display BGColor STRING 1 32 27h 0 RWD red
Display FGColor STRING 1 32 27h 0 RWD black
Alarm sound BOOL 1 4 27h 0 RWD y
Warning DIR
Write system messageBOOL 1 4 >99d 0 RWD y
Write Elog message BOOL 1 4 >99d 0 RWD n
System message interINT 1 4 >99d 0 RWD 60
System message last DWORD 1 4 >99d 0 RWD 0
Execute command STRING 1 256 >99d 0 RWD
Execute interval INT 1 4 >99d 0 RWD 0
Execute last DWORD 1 4 >99d 0 RWD 0
Stop run BOOL 1 4 >99d 0 RWD n
Display BGColor STRING 1 32 >99d 0 RWD red
Display FGColor STRING 1 32 >99d 0 RWD black
Alarm sound BOOL 1 4 27h 0 RWD y

= /Alarms tree structure =
The <span style="color: purple;">/Alarms</span> ODB tree is split into 2 subtrees:
* [[#Alarms subtree|Alarms subtree]] containing as many alarms (i.e. <span style="color: purple;"><alarm-name></span> subtrees) as the user desires. Each alarm must be one of the four defined [[Alarm System#Alarm Types|Alarm Types]]. These also define the conditions that trigger the alarm.
* [[#Classes subtree|Classes subtree]] containing as many classes (i.e. <span style="color: purple;"><class-name></span> subtrees) as the user desires. Each class defines the action to be taken when the alarm occurs. Two Classes (Alarm and Warning) are defined by default (see [[#Example|Example]]).

See also [[Alarm System]].

<br><br>

= Keys in the <span style="color: purple;">''/Alarms''</span> ODB tree =

== <span style="color: purple;">''Alarm system active''</span> ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

If this key in the [[#top|/Alarms ODB tree]]
is set to "y", the alarm system is active. Set to "n" to deactivate.

<br>
---------
<br>

== <span style="color: purple;">''Alarms''</span> subtree ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

Sub-tree in the [[#top|/Alarms ODB tree]] defining each individual alarm condition.

<br>
---------
<br>

=== <span style="color: purple;">''<alarm-name>''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

This subtree in the [[#Alarms subtree|/Alarms/alarms subtree]] specifies the ''name'' of one of the defined alarms, where ''name'' is substituted for <alarm-name>. This subtree will be repeated with a different name for each defined alarm.
In the [[#Example|example]] two ''<alarm-name>'' subtrees are shown, called "''demo odb''" and "''demo periodic''"

<br>
---------
<br>

==== <span style="color: purple;">''Active''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

If this key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is set to "y" , this particular alarm is active.

<br>
---------
<br>

==== <span style="color: purple;">''Triggered''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>

If this key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is non-zero, this alarm has been triggered. Filled by System.

<br>
---------
<br>

==== <span style="color: purple;">''Type''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] must be one of the listed [[#Alarm Type|Alarm Types]].

<br>
---------
<br>

==== <span style="color: purple;">''Check interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 60
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] contains the
frequency in seconds at which this alarm condition is to be checked by the alarm system.

<br>
---------
<br>

==== <span style="color: purple;">''Checked last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is written by the Alarm System. It notes the UNIX timestamp when the alarm condition was last checked.

<br>
---------
<br>

==== <span style="color: purple;">''Trigger count''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is written by the Alarm System. It notes how many consecutive checks of the alarm condition have failed.

<br>
---------
<br>

==== <span style="color: purple;">''Trigger count required''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] can be set by the user.

If it is set to 0 or 1 then the alarm will be triggered as soon as the failure condition is met.

If it is set to a number greater than 1 (N), then the alarm will only be triggered if the failure condition is met for N consecutive periods. The period is defined by the [[#Check interval|Check interval]] parameter for this alarm. This feature may be useful if transient failures are to be tolerated, but persistent failures indicate a real problem (e.g. if a brief excess voltage is okay when a device is ramping up, but a consistent excess voltage indicates a hardware problem).

If 'Check interval' is 10 and 'Trigger count required' is 3, then the alarm will only be triggered if the failure condition is met for 30s in total.

<br>
---------
<br>

==== <span style="color: purple;">''Time triggered first''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is written by the Alarm System.

<br>
---------
<br>

==== <span style="color: purple;">''Time triggered last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is written by the Alarm System.

<br>
---------
<br>

==== <span style="color: purple;">''Condition''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] contains
the condition on which alarm should trigger for [[#/Alarms tree structure|evaluated alarms]]. See [[#Evaluated Alarm conditions]].

<br>
---------
<br>

==== <span style="color: purple;">''Alarm class''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] is set to one of the existing Alarm classes, e.g. the defaults "Alarm","Warning" or a user-defined class, e.g. "Caution".
The Alarm class must be defined in the [[#<class-name> subtree|Classes subtree]].

<br>
---------
<br>

==== <span style="color: purple;">''Alarm message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:'''
</div>

This key in the [[#<alarm-name> subtree|<alarm-name> subtree]] constains
the message to be written when alarm triggers.

<br>
---------
<br>

== <span style="color: purple;">''Classes''</span> subtree ==
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

Sub-tree in the /Alarms ODB tree defining each individual alarm class.
Each class defines the individual action to be performed by a predefined and requested alarm.

<br>
---------
<br>

=== <span style="color: purple;">''<class-name>''</span> subtree ===
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DIR
</div>

This subtree in the [[#Classes subtree|Classes subtree]] defines one of the alarm classes of name ''name'', where ''name'' is substituted for <class-name>. This subtree will be repeated with a different name for each defined class. In the [[#Example of an /Alarms tree|example above]], two <class-name> subtrees are shown, named "Alarm" and "Warning".

<br>
---------
<br>

==== <span style="color: purple;">''Write System Message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "y"
</div>

If this key in the [[#<class-name> subtree|<class-name> subtree]] is set to "y", a message will be sent to the [[System log]] when an alarm with this [[#Alarm class|alarm class]] is triggered.

<br>
---------
<br>

==== <span style="color: purple;">''Write Elog Message''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

If this key in the [[#<class-name> subtree|<class-name> subtree]] is
set to "y", a message will be written to the Elog when an alarm with this [[#Alarm class|alarm class]] is triggered.

<br>
---------
<br>

==== <span style="color: purple;">''System message interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 60
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
interval in seconds between successive system messages when an alarm with this [[#Alarm class|alarm class]] is triggered.

Set this key to 0 to ensure that every alarm is recorded into the [[Message System#MIDAS Log file|MIDAS log file]].

'''See important note ''' on the [[Alarm System#Implementation of the MIDAS Alarm System|implementation of this key]] by the alarm system.

<br>
---------
<br>

==== <span style="color: purple;">''System message last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] contains the time when the last alarm system
message was written. It is filled by the alarm system.

<br>
---------
<br>

==== <span style="color: purple;">''Execute command''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' ""
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] may contain a
command to be executed when an alarm with this [[#Alarm class|alarm class]] is triggered.
This parameter can be used to trigger [[#Alarm triggers Email or SMS|Email or SMS]] alerts.

<br>
---------
<br>

==== <span style="color: purple;">''Execute interval''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' INT
* '''Default:''' 0
</div>

When an alarm with this [[#Alarm class|alarm class]] is triggered, if a valid
[[#Execute command|Execute command]] is supplied, the command will be repeated at an interval in seconds designated by this key in the [[#<class-name> subtree|<class-name> subtree]], providing the interval set is greater than 0.

<br>
---------
<br>

==== <span style="color: purple;">''Execute last''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' DWORD
* '''Default:''' 0
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]]
contains the time when the alarm system last executed the command in the key [[#Execute command|Execute command]].
It is filled by the alarm system.

<br>
---------
<br>

==== <span style="color: purple;">''Stop run''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' "n"
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] if set to "y"
will cause the run to stop when an alarm with this [[#Alarm class|alarm class]] is triggered.

<br>
---------
<br>

==== <span style="color: purple;">''Display BGColor''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "red"
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
background colour of the alarm banner on the [[mhttpd]] [[Status Page]]. The alarm banner
appears if the alarm is triggered.

<br>
---------
<br>

==== <span style="color: purple;">''Display FGColor''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' STRING
* '''Default:''' "black"
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] contains the
foreground colour of the alarm banner on the [[mhttpd]] [[Status Page]]. The alarm banner
appears if the alarm is triggered.

<br>
---------
<br>

==== <span style="color: purple;">''Alarm sound''</span> ====
<div style="column-count:3;-moz-column-count:3;-webkit-column-count:3">
* '''Type:''' BOOL
* '''Default:''' y
</div>

This key in the [[#<class-name> subtree|<class-name> subtree]] states whether this alarm
should produce a sound in a user's web browser or not. (Historically all alarms produced a
sound, but some experiments want to distinguish between "really bad" and "not so bad" alarms).

Note that all the following conditions must be met for the alarm sound to be heard:
* This key is set to 'y' for the alarm that gets triggered.
* The ODB key [[#Alarm_system_active|/Alarms/Alarm system active]] is 'y'.
* On the [[Config_Page|Config]] webpage, the 'Enable alarm sound' checkbox is ticked and the 'Alarm volume' is > 0 (this is a per-user setting).
* The user hasn't muted their speakers.

[[Category:ODB Tree]]
[[Category:Alarms]]

Message Page

2024-12-18T00:32:30Z

Bsmith:

{{Pagelinks}}

= Links =
{{mhttpdpages1|[[Message System]]}}

= Purpose =
The purpose of the [[mhttpd]] Message page is to
display the contents of the MIDAS [[Message System|Messages log file]] in blocks of 100 lines starting with the most recent messages. This log file contains system and user messages generated by applications connected to the experiment. See [[Message System]] for details.

= Access the Message page =
The Message Page is accessed from the [[Status Page]] (or one of the other Pages) by clicking on the menu-button
<span style="color: #444444; background-color: #CCCCCC; font-style:italic; font-size: 90; padding:0.25em;
padding-left: 0.5em;padding-right: 0.5em;border:1px solid #808080;border-radius: 5px;margin-bottom:1px;">Messages</span> .

;Note
:If "Messages" button is not present on the Status Page, it may have been [[Status Page#page-switch-buttons|suppressed]].

= Example =
[[File:message_page.png|500px|left|Figure 1 Example of Messages page for an experiment, Click to enlarge]]
An example of the Message page is shown in Figure 1.

Error messages (i.e. those of [[Message System#Message Types|Message Type]] MERROR) are shown in red. The other messages shown are information messages of [[Message System#Message Types|Message Type]] MINFO.

<div style="clear:both"> </div>
= Filtering and searching for messages =

[[File:message_page_filters.png|500px|left|Figure 2 Filters available, Click to enlarge]]
As of December 2024, MIDAS messages can be filtered using multiple queries. There are 5 filters available, and you can apply multiple filters simultaneously if desired.

After typing the filters, one needs to '''press enter or press the 'filter' button''' to start the filtering process. If the filtering takes a long time, the process can be interrupting by clicking the mouse anywhere in the webpage.

Messages that match the filters will then appear at the top of the message list, highlighted in green. All the non-matching messages then follow with the regular background colours.

<div style="clear:both"> </div>
The different filters are:<br>
<span style="color:#eb463d; font-weight:bold;">Program Name</span>: Filter messages based on the name of the program (e.g. Sequencer, mhttpd)<br>
<span style="color:#4295ae; font-weight:bold;">Status</span>: Show only info/error messages etc<br>
<span style="color:#56bb6c; font-weight:bold;">Time</span>: Find messages at a specific timestamp. It searches from the start of the timestamp associated with the message, so "09:45" will find all messages at 9:45am, "9:45" will not match anything (as the timestamps start with 09), and "09:45:56.237" will match only messages at that specific timestamp. Only the time portion can be searched, not the date.<br>
<span style="color:#f3be69; font-weight:bold;">Search Text</span>: Search the actual message content<br>
<span style="color:#98bdf9; font-weight:bold;">Hour</span>: Show only the last x hours/days<br>

[[Category:mhttpd Pages]]
[[Category:Messages]]

2023-10-11T22:05:45Z

Bsmith: Created page with "{{Pagelinks}} = Links = {{mhttpdpages}} = Purpose = The purpose of the mhttpd equipment pages is to allow the user to view any Variables related to an equipment. = Acc..."

{{Pagelinks}}

= Links =
{{mhttpdpages}}

= Purpose =
The purpose of the [[mhttpd]] equipment pages is to allow the user to view any Variables related to an equipment.

= Access the equipment page =

The main [[Status Page]] contains a list of all the equipment in an experiment (with each equipment being defined by a frontend). The name of each equipment on that page is a link to the relevant equipment page.

= Configuring the equipment page =

There are several ODB keys that can be defined in {{Odbpath|path=/Equipment/<equip_name>/}} that affect the behaviour of this webpage. See [[/Equipment_ODB_tree#Settings_subtree|the Equipment ODB tree]] documentation for full details, but in brief:

* "/Equipment/<equip_name>/Variables/" contains the Variables to show on this page (and to record in the history system).
* "/Equipment/<equip_name>/Settings/Names" or "/Equipment/<equip_name>/Settings/Names <variable>" contains the name of each element in the Variables arrays (e.g. channel names if recording the current of multiple channels).
* "/Equipment/<equip_name>/Settings/Unit <variable>" contains the units in which a variable is measured.
* "/Equipment/<equip_name>/Settings/Editable" contains a comma-separated list of variables that can be edited on the Equipment page.

All the settings are optional, and must be created by the user if desired.

= Example configuration and display =

Click to enlarge each image...

<gallery widths="300px" mode="packed">
Equipment_Variables.png|Variables
Equipment_Settings.png|Settings
Equipment_Page.png|Resulting display
</gallery>

File:Equipment Settings.png

2023-10-11T22:01:44Z

Bsmith:

File:Equipment Variables.png

2023-10-11T22:01:31Z

Bsmith:

File:Equipment Page.png

2023-10-11T22:00:05Z

Bsmith: