1

#!/usr/bin/env python

     2

# -*- coding: utf-8 -*-

     3

     4

# This file is part of Beremiz runtime.

     5

#

     6

# Copyright (C) 2020: Mario de Sousa

     7

#

     8

# See COPYING.Runtime file for copyrights details.

     9

#

    10

# This library is free software; you can redistribute it and/or

    11

# modify it under the terms of the GNU Lesser General Public

    12

# License as published by the Free Software Foundation; either

    13

# version 2.1 of the License, or (at your option) any later version.

    14

    15

# This library is distributed in the hope that it will be useful,

    16

# but WITHOUT ANY WARRANTY; without even the implied warranty of

    17

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    18

# Lesser General Public License for more details.

    19

    20

# You should have received a copy of the GNU Lesser General Public

    21

# License along with this library; if not, write to the Free Software

    22

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

    23

    24

    25

    26

    27

##############################################################################################

    28

# This file implements an extension to the web server embedded in the Beremiz_service.py     #

    29

# runtime manager (webserver is in runtime/NevowServer.py).                                  #

    30

#                                                                                            #

    31

# The extension implemented in this file allows for runtime configuration                    #

    32

# of Modbus plugin parameters                                                                #

    33

##############################################################################################

    34

    35

    36

    37

import json

    38

import os

    39

import ctypes

    40

import string

    41

import hashlib

    42

    43

from formless import annotate, webform

    44

    45

import runtime.NevowServer as NS

    46

    47

# Directory in which to store the persistent configurations

    48

# Should be a directory that does not get wiped on reboot!

    49

_ModbusConfFiledir = WorkingDir

    50

    51

# List of all Web Extension Setting nodes we are handling.

    52

# One WebNode each for:

    53

#   - Modbus TCP client 

    54

#   - Modbus TCP server

    55

#   - Modbus RTU client

    56

#   - Modbus RTU slave

    57

# configured in the loaded PLC (i.e. the .so file loaded into memory)

    58

# Each entry will be a dictionary. See _AddWebNode() for the details

    59

# of the data structure in each entry.

    60

_WebNodeList = []

    61

    62

    63

    64

    65

class MB_StrippedString(annotate.String):

    66

    def __init__(self, *args, **kwargs):

    67

        annotate.String.__init__(self, strip = True, *args, **kwargs)

    68

    69

    70

class MB_StopBits(annotate.Choice):

    71

    _choices = [0, 1, 2]

    72

    73

    def coerce(self, val, configurable):

    74

        return int(val)

    75

    def __init__(self, *args, **kwargs):

    76

        annotate.Choice.__init__(self, choices = self._choices, *args, **kwargs)

    77

    78

    79

class MB_Baud(annotate.Choice):

    80

    _choices = [110, 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200]

    81

    82

    def coerce(self, val, configurable):

    83

        return int(val)

    84

    def __init__(self, *args, **kwargs):

    85

        annotate.Choice.__init__(self, choices = self._choices, *args, **kwargs)

    86

    87

    88

class MB_Parity(annotate.Choice):

    89

    # For more info on what this class really does, have a look at the code in

    90

    # file twisted/nevow/annotate.py

    91

    # grab this code from $git clone https://github.com/twisted/nevow/

    92

    # 

    93

    # Warning: do _not_ name this variable choice[] without underscore, as that name is

    94

    # already used for another similar variable by the underlying class annotate.Choice

    95

    _choices = [  0,      1,      2  ]

    96

    _label   = ["none", "odd", "even"]

    97

    98

    def choice_to_label(self, key):

    99

        #PLCObject.LogMessage("Modbus web server extension::choice_to_label()  " + str(key))

   100

        return self._label[key]

   101

   102

    def coerce(self, val, configurable):

   103

        """Coerce a value with the help of an object, which is the object

   104

        we are configuring.

   105

        """

   106

        # Basically, make sure the value the user introduced is valid, and transform

   107

        # into something that is valid if necessary or mark it as an error 

   108

        # (by raising an exception ??).

   109

        #

   110

        # We are simply using this functions to transform the input value (a string)

   111

        # into an integer. Note that although the available options are all

   112

        # integers (0, 1 or 2), even though what is shown on the user interface

   113

        # are actually strings, i.e. the labels), these parameters are for some 

   114

        # reason being parsed as strings, so we need to map them back to an

   115

        # integer.

   116

        #

   117

        #PLCObject.LogMessage("Modbus web server extension::coerce  " + val )

   118

        return int(val)

   119

   120

    def __init__(self, *args, **kwargs):

   121

        annotate.Choice.__init__(self, 

   122

                                 choices   = self._choices,

   123

                                 stringify = self.choice_to_label,

   124

                                 *args, **kwargs)

   125

   126

   127

   128

# Parameters we will need to get from the C code, but that will not be shown

   129

# on the web interface. Common to all modbus entry types (client/server, tcp/rtu/ascii)

   130

#

   131

# The annotate type entry is basically useless and is completely ignored.

   132

# We kee that entry so that this list can later be correctly merged with the

   133

# following lists...

   134

General_parameters = [

   135

    #    param. name       label                        ctype type         annotate type

   136

    # (C code var name)   (used on web interface)      (C data type)       (web data type)

   137

    #                                                                      (annotate.String,

   138

    #                                                                       annotate.Integer, ...)

   139

    ("config_name"      , _("")                      , ctypes.c_char_p,    annotate.String),

   140

    ("addr_type"        , _("")                      , ctypes.c_char_p,    annotate.String)

   141

    ]                                                                      

   142

   143

# Parameters we will need to get from the C code, and that _will_ be shown

   144

# on the web interface.

   145

TCPclient_parameters = [                                                   

   146

    #    param. name       label                        ctype type         annotate type

   147

    # (C code var name)   (used on web interface)      (C data type)       (web data type)

   148

    #                                                                      (annotate.String,

   149

    #                                                                       annotate.Integer, ...)

   150

    ("host"             , _("Remote IP Address")     , ctypes.c_char_p,    MB_StrippedString),

   151

    ("port"             , _("Remote Port Number")    , ctypes.c_char_p,    MB_StrippedString),

   152

    ("comm_period"      , _("Invocation Rate (ms)")  , ctypes.c_ulonglong, annotate.Integer )

   153

    ]

   154

   155

RTUclient_parameters = [                                                   

   156

    #    param. name       label                        ctype type         annotate type

   157

    # (C code var name)   (used on web interface)      (C data type)       (web data type)

   158

    #                                                                      (annotate.String,

   159

    #                                                                       annotate.Integer, ...)

   160

    ("device"           , _("Serial Port")           , ctypes.c_char_p,    MB_StrippedString),

   161

    ("baud"             , _("Baud Rate")             , ctypes.c_int,       MB_Baud         ),

   162

    ("parity"           , _("Parity")                , ctypes.c_int,       MB_Parity       ),

   163

    ("stop_bits"        , _("Stop Bits")             , ctypes.c_int,       MB_StopBits     ),

   164

    ("comm_period"      , _("Invocation Rate (ms)")  , ctypes.c_ulonglong, annotate.Integer)

   165

    ]

   166

   167

TCPserver_parameters = [                                                   

   168

    #    param. name       label                        ctype type         annotate type

   169

    # (C code var name)   (used on web interface)      (C data type)       (web data type)

   170

    #                                                                      (annotate.String,

   171

    #                                                                       annotate.Integer, ...)

   172

    ("host"             , _("Local IP Address")      , ctypes.c_char_p,    MB_StrippedString),

   173

    ("port"             , _("Local Port Number")     , ctypes.c_char_p,    MB_StrippedString),

   174

    ("slave_id"         , _("Slave ID")              , ctypes.c_ubyte,     annotate.Integer )

   175

    ]

   176

   177

RTUslave_parameters = [                                                   

   178

    #    param. name       label                        ctype type         annotate type

   179

    # (C code var name)   (used on web interface)      (C data type)       (web data type)

   180

    #                                                                      (annotate.String,

   181

    #                                                                       annotate.Integer, ...)

   182

    ("device"           , _("Serial Port")           , ctypes.c_char_p,    MB_StrippedString),

   183

    ("baud"             , _("Baud Rate")             , ctypes.c_int,       MB_Baud         ),

   184

    ("parity"           , _("Parity")                , ctypes.c_int,       MB_Parity       ),

   185

    ("stop_bits"        , _("Stop Bits")             , ctypes.c_int,       MB_StopBits     ),

   186

    ("slave_id"         , _("Slave ID")              , ctypes.c_ubyte,     annotate.Integer)

   187

    ]

   188

   189

   190

   191

   192

# Dictionary containing List of Web viewable parameters

   193

# Note: the dictionary key must be the same as the string returned by the 

   194

# __modbus_get_ClientNode_addr_type()

   195

# __modbus_get_ServerNode_addr_type()

   196

# functions implemented in C (see modbus/mb_runtime.c)

   197

_client_WebParamListDict = {}

   198

_client_WebParamListDict["tcp"  ] = TCPclient_parameters

   199

_client_WebParamListDict["rtu"  ] = RTUclient_parameters

   200

_client_WebParamListDict["ascii"] = []  # (Note: ascii not yet implemented in Beremiz modbus plugin)

   201

   202

_server_WebParamListDict = {}

   203

_server_WebParamListDict["tcp"  ] = TCPserver_parameters

   204

_server_WebParamListDict["rtu"  ] = RTUslave_parameters

   205

_server_WebParamListDict["ascii"] = []  # (Note: ascii not yet implemented in Beremiz modbus plugin)

   206

   207

WebParamListDictDict = {}

   208

WebParamListDictDict['client'] = _client_WebParamListDict

   209

WebParamListDictDict['server'] = _server_WebParamListDict

   210

   211

   212

   213

   214

   215

   216

def _SetModbusSavedConfiguration(WebNode_id, newConfig):

   217

    """ Stores a dictionary in a persistant file containing the Modbus parameter configuration """

   218

    WebNode_entry = _WebNodeList[WebNode_id]

   219

   220

    if WebNode_entry["DefaultConfiguration"] == newConfig:

   221

   222

        _DelModbusSavedConfiguration(WebNode_id)

   223

        WebNode_entry["ModbusSavedConfiguration"] = None

   224

   225

    else:

   226

   227

        # Add the addr_type and node_type to the data that will be saved to file

   228

        # This allows us to confirm the saved data contains the correct addr_type

   229

        # when loading from file

   230

        save_info = {}

   231

        save_info["addr_type"] = WebNode_entry["addr_type"]

   232

        save_info["node_type"] = WebNode_entry["node_type"]

   233

        save_info["config"   ] = newConfig

   234

   235

        filename = WebNode_entry["filename"]

   236

   237

        with open(os.path.realpath(filename), 'w') as f:

   238

            json.dump(save_info, f, sort_keys=True, indent=4)

   239

   240

        WebNode_entry["ModbusSavedConfiguration"] = newConfig

   241

   242

   243

   244

   245

def _DelModbusSavedConfiguration(WebNode_id):

   246

    """ Deletes the file cotaining the persistent Modbus configuration """

   247

    filename = _WebNodeList[WebNode_id]["filename"]

   248

   249

    if os.path.exists(filename):

   250

        os.remove(filename)

   251

   252

   253

   254

   255

def _GetModbusSavedConfiguration(WebNode_id):

   256

    """

   257

    Returns a dictionary containing the Modbus parameter configuration

   258

    that was last saved to file. If no file exists, or file contains 

   259

    wrong addr_type (i.e. 'tcp', 'rtu' or 'ascii' -> does not match the

   260

    addr_type of the WebNode_id), then return None

   261

    """

   262

    filename = _WebNodeList[WebNode_id]["filename"]

   263

    try:

   264

        #if os.path.isfile(filename):

   265

        save_info = json.load(open(os.path.realpath(filename)))

   266

    except Exception:    

   267

        return None

   268

   269

    if save_info["addr_type"] != _WebNodeList[WebNode_id]["addr_type"]:

   270

        return None

   271

    if save_info["node_type"] != _WebNodeList[WebNode_id]["node_type"]:

   272

        return None

   273

    if "config" not in save_info:

   274

        return None

   275

   276

    saved_config = save_info["config"]

   277

   278

    #if _CheckConfiguration(saved_config):

   279

    #    return saved_config

   280

    #else:

   281

    #    return None

   282

   283

    return saved_config

   284

   285

   286

   287

def _GetModbusPLCConfiguration(WebNode_id):

   288

    """

   289

    Returns a dictionary containing the current Modbus parameter configuration

   290

    stored in the C variables in the loaded PLC (.so file)

   291

    """

   292

    current_config = {}

   293

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   294

    WebParamList   = _WebNodeList[WebNode_id]["WebParamList"]

   295

    GetParamFuncs  = _WebNodeList[WebNode_id]["GetParamFuncs"]

   296

   297

    for par_name, x1, x2, x3 in WebParamList:

   298

        value = GetParamFuncs[par_name](C_node_id)

   299

        if value is not None:

   300

            current_config[par_name] = value

   301

   302

    return current_config

   303

   304

   305

   306

def _SetModbusPLCConfiguration(WebNode_id, newconfig):

   307

    """

   308

    Stores the Modbus parameter configuration into the

   309

    the C variables in the loaded PLC (.so file)

   310

    """

   311

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   312

    SetParamFuncs  = _WebNodeList[WebNode_id]["SetParamFuncs"]

   313

   314

    for par_name in newconfig:

   315

        value = newconfig[par_name]

   316

        if value is not None:

   317

            SetParamFuncs[par_name](C_node_id, value)

   318

   319

   320

   321

   322

def _GetModbusWebviewConfigurationValue(ctx, WebNode_id, argument):

   323

    """

   324

    Callback function, called by the web interface (NevowServer.py)

   325

    to fill in the default value of each parameter of the web form

   326

   327

    Note that the real callback function is a dynamically created function that

   328

    will simply call this function to do the work. It will also pass the WebNode_id 

   329

    as a parameter.

   330

    """    

   331

    try:

   332

        return _WebNodeList[WebNode_id]["WebviewConfiguration"][argument.name]

   333

    except Exception:

   334

        return ""

   335

   336

   337

   338

def OnModbusButtonSave(**kwargs):

   339

    """

   340

    Function called when user clicks 'Save' button in web interface

   341

    The function will configure the Modbus plugin in the PLC with the values

   342

    specified in the web interface. However, values must be validated first!

   343

   344

    Note that this function does not get called directly. The real callback

   345

    function is the dynamic __OnButtonSave() function, which will add the 

   346

    "WebNode_id" argument, and call this function to do the work.

   347

    """

   348

   349

    #PLCObject.LogMessage("Modbus web server extension::OnModbusButtonSave()  Called")

   350

   351

    newConfig    = {}

   352

    WebNode_id   =  kwargs.get("WebNode_id", None)

   353

    WebParamList = _WebNodeList[WebNode_id]["WebParamList"]

   354

   355

    for par_name, x1, x2, x3 in WebParamList:

   356

        value = kwargs.get(par_name, None)

   357

        if value is not None:

   358

            newConfig[par_name] = value

   359

   360

    # First check if configuration is OK.

   361

    # Note that this is not currently required, as we use drop down choice menus

   362

    # for baud, parity and sop bits, so the values should always be correct!

   363

    #if not _CheckWebConfiguration(newConfig):

   364

    #    return

   365

   366

    # store to file the new configuration so that 

   367

    # we can recoup the configuration the next time the PLC

   368

    # has a cold start (i.e. when Beremiz_service.py is retarted)

   369

    _SetModbusSavedConfiguration(WebNode_id, newConfig)

   370

   371

    # Configure PLC with the current Modbus parameters

   372

    _SetModbusPLCConfiguration(WebNode_id, newConfig)

   373

   374

    # Update the viewable configuration

   375

    # The PLC may have coerced the values on calling _SetModbusPLCConfiguration()

   376

    # so we do not set it directly to newConfig

   377

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = _GetModbusPLCConfiguration(WebNode_id)

   378

   379

   380

   381

def OnModbusButtonReset(**kwargs):

   382

    """

   383

    Function called when user clicks 'Delete' button in web interface

   384

    The function will delete the file containing the persistent

   385

    Modbus configution

   386

    """

   387

   388

    WebNode_id = kwargs.get("WebNode_id", None)

   389

   390

    # Delete the file

   391

    _DelModbusSavedConfiguration(WebNode_id)

   392

   393

    # Set the current configuration to the default (hardcoded in C)

   394

    new_config = _WebNodeList[WebNode_id]["DefaultConfiguration"]

   395

    _SetModbusPLCConfiguration(WebNode_id, new_config)

   396

   397

    #Update the webviewconfiguration

   398

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = new_config

   399

   400

    # Reset ModbusSavedConfiguration

   401

    _WebNodeList[WebNode_id]["ModbusSavedConfiguration"] = None

   402

   403

   404

   405

   406

   407

def _AddWebNode(C_node_id, node_type, GetParamFuncs, SetParamFuncs):

   408

    """

   409

    Load from the compiled code (.so file, aloready loaded into memmory)

   410

    the configuration parameters of a specific Modbus plugin node.

   411

    This function works with both client and server nodes, depending on the

   412

    Get/SetParamFunc dictionaries passed to it (either the client or the server

   413

    node versions of the Get/Set functions)

   414

    """

   415

    WebNode_entry = {}

   416

   417

    # Get the config_name from the C code...

   418

    config_name = GetParamFuncs["config_name"](C_node_id)

   419

    # Get the addr_type from the C code...

   420

    # addr_type will be one of "tcp", "rtu" or "ascii"

   421

    addr_type   = GetParamFuncs["addr_type"  ](C_node_id)   

   422

    # For some operations we cannot use the config name (e.g. filename to store config)

   423

    # because the user may be using characters that are invalid for that purpose ('/' for

   424

    # example), so we create a hash of the config_name, and use that instead.

   425

    config_hash = hashlib.md5(config_name).hexdigest()

   426

   427

    #PLCObject.LogMessage("Modbus web server extension::_AddWebNode("+str(C_node_id)+") config_name="+config_name)

   428

   429

    # Add the new entry to the global list

   430

    # Note: it is OK, and actually necessary, to do this _before_ seting all the parameters in WebNode_entry

   431

    #       WebNode_entry will be stored as a reference, so we can later insert parameters at will.

   432

    global _WebNodeList

   433

    _WebNodeList.append(WebNode_entry)

   434

    WebNode_id = len(_WebNodeList) - 1

   435

   436

    # store all WebNode relevant data for future reference

   437

    #

   438

    # Note that "WebParamList" will reference one of:

   439

    #  - TCPclient_parameters, TCPserver_parameters, RTUclient_parameters, RTUslave_parameters

   440

    WebNode_entry["C_node_id"    ] = C_node_id

   441

    WebNode_entry["config_name"  ] = config_name 

   442

    WebNode_entry["config_hash"  ] = config_hash

   443

    WebNode_entry["filename"     ] = os.path.join(_ModbusConfFiledir, "Modbus_config_" + config_hash + ".json")

   444

    WebNode_entry["GetParamFuncs"] = GetParamFuncs

   445

    WebNode_entry["SetParamFuncs"] = SetParamFuncs

   446

    WebNode_entry["WebParamList" ] = WebParamListDictDict[node_type][addr_type] 

   447

    WebNode_entry["addr_type"    ] = addr_type  # 'tcp', 'rtu', or 'ascii' (as returned by C function)

   448

    WebNode_entry["node_type"    ] = node_type  # 'client', 'server'

   449

   450

   451

    # Dictionary that contains the Modbus configuration currently being shown

   452

    # on the web interface

   453

    # This configuration will almost always be identical to the current

   454

    # configuration in the PLC (i.e., the current state stored in the 

   455

    # C variables in the .so file).

   456

    # The configuration viewed on the web will only be different to the current 

   457

    # configuration when the user edits the configuration, and when

   458

    # the user asks to save an edited configuration that contains an error.

   459

    WebNode_entry["WebviewConfiguration"] = None

   460

   461

    # Upon PLC load, this Dictionary is initialised with the Modbus configuration

   462

    # hardcoded in the C file

   463

    # (i.e. the configuration inserted in Beremiz IDE when project was compiled)

   464

    WebNode_entry["DefaultConfiguration"] = _GetModbusPLCConfiguration(WebNode_id)

   465

    WebNode_entry["WebviewConfiguration"] = WebNode_entry["DefaultConfiguration"]

   466

   467

    # Dictionary that stores the Modbus configuration currently stored in a file

   468

    # Currently only used to decide whether or not to show the "Delete" button on the

   469

    # web interface (only shown if "ModbusSavedConfiguration" is not None)

   470

    SavedConfig = _GetModbusSavedConfiguration(WebNode_id)

   471

    WebNode_entry["ModbusSavedConfiguration"] = SavedConfig

   472

   473

    if SavedConfig is not None:

   474

        _SetModbusPLCConfiguration(WebNode_id, SavedConfig)

   475

        WebNode_entry["WebviewConfiguration"] = SavedConfig

   476

   477

    # Define the format for the web form used to show/change the current parameters

   478

    # We first declare a dynamic function to work as callback to obtain the default values for each parameter

   479

    # Note: We transform every parameter into a string

   480

    #       This is not strictly required for parameters of type annotate.Integer that will correctly

   481

    #           accept the default value as an Integer python object

   482

    #       This is obviously also not required for parameters of type annotate.String, that are

   483

    #           always handled as strings.

   484

    #       However, the annotate.Choice parameters (and all parameters that derive from it,

   485

    #           sucn as Parity, Baud, etc.) require the default value as a string

   486

    #           even though we store it as an integer, which is the data type expected

   487

    #           by the set_***() C functions in mb_runtime.c

   488

    def __GetWebviewConfigurationValue(ctx, argument):

   489

        return str(_GetModbusWebviewConfigurationValue(ctx, WebNode_id, argument))

   490

   491

    webFormInterface = [(name, web_dtype (label=web_label, default=__GetWebviewConfigurationValue)) 

   492

                    for name, web_label, c_dtype, web_dtype in WebNode_entry["WebParamList"]]

   493

   494

    # Configure the web interface to include the Modbus config parameters

   495

    def __OnButtonSave(**kwargs):

   496

        OnModbusButtonSave(WebNode_id=WebNode_id, **kwargs)

   497

   498

    WebSettings = NS.newExtensionSetting("Modbus #"+ str(WebNode_id), config_hash)

   499

   500

    WebSettings.addSettings(