Frontends: programming

#include <stdio.h>
#include <math.h> // M_PI

#include "tmfe.h"

class EqPeriodic : public TMFeEquipment {
    public:
        EqPeriodic(const char* eqname, const char* eqfilename) : TMFeEquipment(eqname, eqfilename) {
            fEqConfReadConfigFromOdb = false;
            fEqConfEventID = 2;
            fEqConfBuffer = "SYSTEM";
            fEqConfPeriodMilliSec = 1000; // in milliseconds
            fEqConfLogHistory = 1;
            fEqConfReadOnlyWhenRunning = true;
            fEqConfWriteEventsToOdb = true;
        }

        void HandlePeriodic() {
            char buf[1024];

            ComposeEvent(buf, sizeof(buf));
            BkInit(buf, sizeof(buf));

            /* create SCLR bank */
            uint32_t* pdata = (uint32_t*)BkOpen(buf, "PRDC", TID_UINT32);

            /* following code "simulates" some values in sine wave form */
            for (int a = 0; a < 16; a++) {
                *pdata++ = 100*sin(M_PI*time(NULL)/60+a/2.0)+100;
            }

            BkClose(buf, pdata);

            EqSendEvent(buf);
        }
};

class FeExample: public TMFrontend {
    public:
        FeExample() {
            /* register with the framework */
            FeSetName("Sample Frontend");
            FeAddEquipment(new EqTrigger("Trigger", __FILE__));
            FeAddEquipment(new EqPeriodic("Periodic", __FILE__));
        }
};

int main(int argc, char* argv[]) {
    FeExample fe_example;
    return fe_example.FeMain(argc, argv);
}

import midas
import midas.frontend
import midas.event

class MyPeriodicEquipment(midas.frontend.EquipmentBase):
    """
    We define an "equipment" for each logically distinct task that this frontend
    performs. For example, you may have one equipment for reading data from a
    device and sending it to a midas buffer, and another equipment that updates
    summary statistics every 10s.

    Each equipment class you define should inherit from 
    `midas.frontend.EquipmentBase`, and should define a `readout_func` function.
    If you're creating a "polled" equipment (rather than a periodic one), you
    should also define a `poll_func` function in addition to `readout_func`.
    """
    def __init__(self, client):
        # The name of our equipment. This name will be used on the midas status
        # page, and our info will appear in /Equipment/MyPeriodicEquipment in
        # the ODB.
        equip_name = "MyPeriodicEquipment"

        # Define the "common" settings of a frontend. These will appear in
        # /Equipment/MyPeriodicEquipment/Common. The values you set here are
        # only used the very first time this frontend/equipment runs; after 
        # that the ODB settings are used.
        default_common = midas.frontend.InitialEquipmentCommon()
        default_common.equip_type = midas.EQ_PERIODIC
        default_common.buffer_name = "SYSTEM"
        default_common.trigger_mask = 0
        default_common.event_id = 1
        default_common.period_ms = 100
        default_common.read_when = midas.RO_RUNNING
        default_common.log_history = 1

        # You MUST call midas.frontend.EquipmentBase.__init__ in your equipment's __init__ method!
        midas.frontend.EquipmentBase.__init__(self, client, equip_name, default_common)

        # You can set the status of the equipment (appears in the midas status page)
        self.set_status("Initialized")

    def readout_func(self):
        """
        For a periodic equipment, this function will be called periodically
        (every 100ms in this case). It should return either a `midas.event.Event`
        or None (if we shouldn't write an event).
        """

        # In this example, we just make a simple event with one bank.
        event = midas.event.Event()

        # Create a bank (called "MYBK") which in this case will store 8 ints.
        # data can be a list, a tuple or a numpy array.
        data = [1,2,3,4,5,6,7,8]
        event.create_bank("MYBK", midas.TID_INT, data)

        return event

class MyFrontend(midas.frontend.FrontendBase):
    """
    A frontend contains a collection of equipment.
    You can access self.client to access the ODB etc (see `midas.client.MidasClient`).
    """
    def __init__(self):
        # You must call __init__ from the base class.
        midas.frontend.FrontendBase.__init__(self, "myfe_name")

        # You can add equipment at any time before you call `run()`, but doing
        # it in __init__() seems logical.
        self.add_equipment(MyPeriodicEquipment(self.client))

    def begin_of_run(self, run_number):
        """
        This function will be called at the beginning of the run.
        You don't have to define it, but you probably should.
        You can access individual equipment classes through the `self.equipment`
        dict if needed.
        """
        self.set_all_equipment_status("Running", "greenLight")
        self.client.msg("Frontend has seen start of run number %d" % run_number)
        return midas.status_codes["SUCCESS"]

    def end_of_run(self, run_number):
        self.set_all_equipment_status("Finished", "greenLight")
        self.client.msg("Frontend has seen end of run number %d" % run_number)
        return midas.status_codes["SUCCESS"]

    def frontend_exit(self):
        """
        Most people won't need to define this function, but you can use
        it for final cleanup if needed.
        """
        print("Goodbye from user code!")

if __name__ == "__main__":
    # The main executable is very simple - just create the frontend object,
    # and call run() on it.
    with MyFrontend() as my_fe:
        my_fe.run()

TMFeResult HandleBeginRun(int run_number);

# Use the plain TMFeResult constructor. 
# TMFeResult(int code, const std::string& str);
# See $MIDASSYS/include/midas.h for details of pre-defined error codes (like FE_ERR_ODB is 602), but you may use any integer.
# Note that midas defines SUCCESS as 1!
return TMFeResult(FE_ERR_ODB, "Failed to read value from ODB");

# Use a shorthand to say that everything is okay.
return TMFeOk();

# Say there was a failure without specifying a specific midas status code (SUCCESS in midas is 1; this wrapper will set a code of 0)
return TMFeErrorMessage("Failed to read value from ODB");

# Apply some formatting to your error message saying which function had the issue.
# This example will result in a message of "Failed to read value from ODB, some_func() status 602"
return TMFeMidasError("Failed to read value from ODB", "some_func", FE_ERR_ODB);

# Access from anywhere
TMFE::Instance()->

# Access from within a class that derives from TMFeEquipment:
fMfe->

# Access from within a class that derives from TMFrontend:
fMfe->

// Add a message to the midas message log (wrapper around cm_msg()).
// The simplest way to pass the first 3 parameters is via the MINFO or MERROR macros.
// If your compiler supports the __FUNCTION__ macro (which most do), you can use that to automatically generate the value for the 4th argument.
// The subsequent arguments behave like any call to printf/sprintf etc.
// E.g. fMfe->Msg(MINFO, __FUNCTION__, "6 x 3 = %d", 18);
void Msg(int message_type, const char *filename, int line, const char *routine, const char *format, ...);

// Start or stop a run from your code (wrapper around cm_transition()).
void StartRun();
void StopRun();

// Get the current UNIX time in seconds (to microsecond precision).
double GetTime();

// Raise/trigger an alarm (wrapper around al_trigger_alarm()). Uses the "internal" alarm type.
// Pre-defined alarm classes are "Warning" and "Alarm".
TMFeResult TriggerAlarm(const char* alarm_name, const char* message, const char* alarm_class);

// Cancel/reset an alarm
TMFeResult ResetAlarm(const char* alarm_name);

// Wait for up to N seconds for midas to tell us about any ODB updates, RPC calls etc (wrapper around cm_yield()).
// This is automatically called periodically by the frontend system, so you shouldn't need to call it yourself.
void Yield(double secs);

// Sleep the current thread for the specified number of seconds (very similar to ss_sleep()).
void Sleep(double secs);

// This is set to true if the user passes -v as a command-line argument when running the frontend.
bool gfVerbose;

// Current run number.
int  fRunNumber;

// Whether run is running/paused (true) or stopped (false).
bool fStateRunning;

// ODB access via MVOdb.
MVOdb* fOdbRoot;

// ODB handle if using db_* C-style family of functions
HNDLE fDB;

typedef struct {
    char name[NAME_LENGTH];         /**< Equipment name                            */
    EQUIPMENT_INFO info;            /**< See below                                 */
    INT(*readout) (char *, INT);    /**< Pointer to user readout routine           */
    INT(*cd) (INT cmd, PEQUIPMENT); /**< For EQ_SLOW, the class driver routine     */
    DEVICE_DRIVER *driver;          /**< For EQ_SLOW, the device driver list       */
    void *event_descrip;            /**< For FIXED format, text description of format */
    // .... and then some "internal" fields that you don't need to set
} EQUIPMENT;

typedef struct {
    WORD event_id;                   /**< Common/Event ID      */
    WORD trigger_mask;               /**< Common/Trigger mask  */
    char buffer[NAME_LENGTH];        /**< Common/Buffer        */
    INT eq_type;                     /**< Common/Type          */
    INT source;                      /**< Common/Source        */
    char format[8];                  /**< Common/Format        */
    BOOL enabled;                    /**< Common/Enabled       */
    INT read_on;                     /**< Common/Read on       */
    INT period;                      /**< Common/Period        */
    double event_limit;              /**< Common/Event limit   */
    DWORD num_subevents;             /**< Common/Num subevent  */
    INT history;                     /**< Common/Log history   */
    // .... and then some "internal" fields that you don't need to set
} EQUIPMENT_INFO;

MyEquip(const char* eqname, const char* eqfilename) : TMFeEquipment(eqname, eqfilename) { }

midas.frontend.EquipmentBase.__init__(self, client, equip_name, default_common)

// Initialisation - handle any arguments that appeared after "--" on the command-line.
// Order of operations is:
// - HandleArguments()
// - Connect to midas
// - HandleFrontendInit()
// - Call equip->HandleInit() for all equipments
// - HandleFrontendReady()
TMFeResult HandleArguments(const std::vector<std::string>& args);
TMFeResult HandleFrontendInit(const std::vector<std::string>& args);
TMFeResult HandleFrontendReady(const std::vector<std::string>& args);

// Print any usage information to screen (e.g. if you handle any arguments after "--" on the command-line).
void       HandleUsage();

// Do any cleanup just before we disconnect from midas.
void       HandleFrontendExit();

// Set the name of this program as it will appear to other midas clients.
void       FeSetName(const char* program_name);

// Add an equipment.
TMFeResult FeAddEquipment(TMFeEquipment* eq);

// Access to TMFE singleton.
TMFE* fMfe;

// Frontend index (see below).
int  fFeIndex = 0;

// Set this to true if you don't want to allow the frontend to start if a run is already in progress.
bool fFeIfRunningCallExit = false;

// Call the begin-of-run logic for this frontend if the program is started while a run is already in progress.
bool fFeIfRunningCallBeginRun = true;

# `midas.client.MidasClient` - the object we can use for ODB access etc.
self.client 

# (dict of {str: `EquipmentBase`}) - the equipment you added, keyed by equipment name.
self.equipment

# int - the current run state (midas.STATE_RUNNING etc)
self.run_state (int)

-i NNN                  set frontend index number (if running multiple instances of the same frontend)
-h hostname[:tcpport]   connect to MIDAS mserver on given host and tcp port number
-e exptname             connect to given MIDAS experiment
-D                      become a daemon
-O                      become a daemon but keep stdout for saving in a log file: frontend -O >file.log 
-v [level]              set verbosity level (as an integer). A bare `-v` implies `-v 1`
-d                      used for debugging the frontend

TMFeResult HandleInit(const std::vector<std::string>& args);

void HandleUsage();

--help                  print help message
-i NNN                  set frontend index number (if running multiple instances of the same frontend)
-h hostname[:tcpport]   connect to MIDAS mserver on given host and tcp port number
-e exptname             connect to given MIDAS experiment
-D                      become a daemon
-O                      become a daemon but keep stdout for saving in a log file: frontend -O >file.log 2>&1
-v                      print debug output to screen

-i NNN                  set frontend index number (if running multiple instances of the same frontend)
-h hostname[:tcpport]   connect to MIDAS mserver on given host and tcp port number
-e exptname             connect to given MIDAS experiment
-D                      become a daemon
-O                      become a daemon but keep stdout for saving in a log file: frontend -O >file.log 2>&1
-d                      enable debug logging

INT get_frontend_index(void);

# Access to the top-level (from within classes that derive from TMFeEquipment or TMFrontend).
fMfe->fOdbRoot->    # /

# Access to equipment-specific ODB directories (from within classes that derive from TMFeEquipment):
fOdbEq->            # /Equipment/xxx
fOdbEqCommon->      # /Equipment/xxx/Common
fOdbEqSettings->    # /Equipment/xxx/Settings
fOdbEqVariables->   # /Equipment/xxx/Variables
fOdbEqStatistics->  # /Equipment/xxx/Statistics

self.odb_common_dir      # /Equipment/xxx/Common
self.odb_stats_dir       # /Equipment/xxx/Statistics
self.odb_variables_dir   # /Equipment/xxx/Variables
self.odb_settings_dir    # /Equipment/xxx/Settings

TMFeResult HandleBeginRun(int run_number);
TMFeResult HandleEndRun(int run_number);
TMFeResult HandlePauseRun(int run_number);
TMFeResult HandleResumeRun(int run_number);
TMFeResult HandleStartAbortRun(int run_number);

fMfe->SetTransitionSequenceStart(int seqno);
fMfe->SetTransitionSequenceStop(int seqno);
fMfe->SetTransitionSequencePause(int seqno);
fMfe->SetTransitionSequenceResume(int seqno);
fMfe->SetTransitionSequenceStartAbort(int seqno);

INT poll_event(INT source, INT count, BOOL test)

bool HandlePoll();

def poll_func(self):

INT my_readout_function_name(char *pevent, int offset);

// Implement this for a periodic equipment
void HandlePeriodic();

// Implement this for a polled equipment 
void HandlePollRead();

TMFeResult ComposeEvent(char* pevent, size_t size) const;
TMFeResult BkInit(char* pevent, size_t size) const;
void*      BkOpen(char* pevent, const char* bank_name, int bank_type) const;
TMFeResult BkClose(char* pevent, void* ptr) const;

TMFeResult EqSendEvent(const char* event, bool write_to_odb=true);

INT set_equipment_status(const char *name, const char *eq_status, const char *status_class);

TMFeResult EqSetStatus(char const* eq_status, char const* eq_color);

# JRPC handler
TMFeResult HandleRpc(const char* cmd, const char* args, std::string& result);

# BRPC handler
TMFeResult HandleBinaryRpc(const char* cmd, const char* args, std::vector<char>& result);

mkdir build
cd build
cmake ..
make

mkdir build
cd build
cmake ..
make