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

    46

    47

# reference to the PLCObject in runtime/PLCObject.py

    48

# PLCObject is a singleton, created in runtime/__init__.py

    49

_plcobj = None

    50

    51

# reference to the Nevow web server (a.k.a as NS in Beremiz_service.py)

    52

# (Note that NS will reference the NevowServer.py _module_, and not an object/class)

    53

_NS = None

    54

    55

    56

# WorkingDir: the directory on which Beremiz_service.py is running, and where 

    57

#             all the files downloaded to the PLC get stored

    58

_WorkingDir = None

    59

    60

# Directory in which to store the persistent configurations

    61

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

    62

_ModbusConfFiledir = "/tmp"

    63

    64

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

    65

# One WebNode each for:

    66

#   - Modbus TCP client 

    67

#   - Modbus TCP server

    68

#   - Modbus RTU client

    69

#   - Modbus RTU slave

    70

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

    71

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

    72

# of the data structure in each entry.

    73

_WebNodeList = []

    74

    75

    76

    77

    78

class MB_StrippedString(annotate.String):

    79

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

    80

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

    81

    82

    83

class MB_StopBits(annotate.Choice):

    84

    _choices = [0, 1, 2]

    85

    86

    def coerce(self, val, configurable):

    87

        return int(val)

    88

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

    89

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

    90

    91

    92

class MB_Baud(annotate.Choice):

    93

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

    94

    95

    def coerce(self, val, configurable):

    96

        return int(val)

    97

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

    98

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

    99

   100

   101

class MB_Parity(annotate.Choice):

   102

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

   103

    # file twisted/nevow/annotate.py

   104

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

   105

    # 

   106

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

   107

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

   108

    _choices = [  0,      1,      2  ]

   109

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

   110

   111

    def choice_to_label(self, key):

   112

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

   113

        return self._label[key]

   114

   115

    def coerce(self, val, configurable):

   116

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

   117

        we are configuring.

   118

        """

   119

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

   120

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

   121

        # (by raising an exception ??).

   122

        #

   123

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

   124

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

   125

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

   126

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

   127

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

   128

        # integer.

   129

        #

   130

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

   131

        return int(val)

   132

   133

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

   134

        annotate.Choice.__init__(self, 

   135

                                 choices   = self._choices,

   136

                                 stringify = self.choice_to_label,

   137

                                 *args, **kwargs)

   138

   139

   140

   141

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

   142

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

   143

#

   144

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

   145

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

   146

# following lists...

   147

General_parameters = [

   148

    #    param. name       label                        ctype type         annotate type

   149

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

   150

    #                                                                      (annotate.String,

   151

    #                                                                       annotate.Integer, ...)

   152

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

   153

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

   154

    ]                                                                      

   155

   156

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

   157

# on the web interface.

   158

TCPclient_parameters = [                                                   

   159

    #    param. name       label                        ctype type         annotate type

   160

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

   161

    #                                                                      (annotate.String,

   162

    #                                                                       annotate.Integer, ...)

   163

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

   164

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

   165

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

   166

    ]

   167

   168

RTUclient_parameters = [                                                   

   169

    #    param. name       label                        ctype type         annotate type

   170

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

   171

    #                                                                      (annotate.String,

   172

    #                                                                       annotate.Integer, ...)

   173

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

   174

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

   175

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

   176

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

   177

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

   178

    ]

   179

   180

TCPserver_parameters = [                                                   

   181

    #    param. name       label                        ctype type         annotate type

   182

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

   183

    #                                                                      (annotate.String,

   184

    #                                                                       annotate.Integer, ...)

   185

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

   186

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

   187

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

   188

    ]

   189

   190

RTUslave_parameters = [                                                   

   191

    #    param. name       label                        ctype type         annotate type

   192

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

   193

    #                                                                      (annotate.String,

   194

    #                                                                       annotate.Integer, ...)

   195

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

   196

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

   197

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

   198

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

   199

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

   200

    ]

   201

   202

   203

   204

   205

# Dictionary containing List of Web viewable parameters

   206

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

   207

# __modbus_get_ClientNode_addr_type()

   208

# __modbus_get_ServerNode_addr_type()

   209

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

   210

_client_WebParamListDict = {}

   211

_client_WebParamListDict["tcp"  ] = TCPclient_parameters

   212

_client_WebParamListDict["rtu"  ] = RTUclient_parameters

   213

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

   214

   215

_server_WebParamListDict = {}

   216

_server_WebParamListDict["tcp"  ] = TCPserver_parameters

   217

_server_WebParamListDict["rtu"  ] = RTUslave_parameters

   218

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

   219

   220

WebParamListDictDict = {}

   221

WebParamListDictDict['client'] = _client_WebParamListDict

   222

WebParamListDictDict['server'] = _server_WebParamListDict

   223

   224

   225

   226

   227

   228

   229

def _SetSavedConfiguration(WebNode_id, newConfig):

   230

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

   231

   232

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

   233

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

   234

    # when loading from file

   235

    save_info = {}

   236

    save_info["addr_type"] = _WebNodeList[WebNode_id]["addr_type"]

   237

    save_info["node_type"] = _WebNodeList[WebNode_id]["node_type"]

   238

    save_info["config"   ] = newConfig

   239

   240

    filename = _WebNodeList[WebNode_id]["filename"]

   241

   242

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

   243

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

   244

   245

    _WebNodeList[WebNode_id]["SavedConfiguration"] = newConfig

   246

   247

   248

   249

   250

def _DelSavedConfiguration(WebNode_id):

   251

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

   252

    filename = _WebNodeList[WebNode_id]["filename"]

   253

   254

    if os.path.exists(filename):

   255

        os.remove(filename)

   256

   257

   258

   259

   260

def _GetSavedConfiguration(WebNode_id):

   261

    """

   262

    Returns a dictionary containing the Modbus parameter configuration

   263

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

   264

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

   265

    addr_type of the WebNode_id), then return None

   266

    """

   267

    filename = _WebNodeList[WebNode_id]["filename"]

   268

    try:

   269

        #if os.path.isfile(filename):

   270

        save_info = json.load(open(filename))

   271

    except Exception:    

   272

        return None

   273

   274

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

   275

        return None

   276

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

   277

        return None

   278

    if "config" not in save_info:

   279

        return None

   280

   281

    saved_config = save_info["config"]

   282

   283

    #if _CheckConfiguration(saved_config):

   284

    #    return saved_config

   285

    #else:

   286

    #    return None

   287

   288

    return saved_config

   289

   290

   291

   292

def _GetPLCConfiguration(WebNode_id):

   293

    """

   294

    Returns a dictionary containing the current Modbus parameter configuration

   295

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

   296

    """

   297

    current_config = {}

   298

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   299

    WebParamList   = _WebNodeList[WebNode_id]["WebParamList"]

   300

    GetParamFuncs  = _WebNodeList[WebNode_id]["GetParamFuncs"]

   301

   302

    for par_name, x1, x2, x3 in WebParamList:

   303

        value = GetParamFuncs[par_name](C_node_id)

   304

        if value is not None:

   305

            current_config[par_name] = value

   306

   307

    return current_config

   308

   309

   310

   311

def _SetPLCConfiguration(WebNode_id, newconfig):

   312

    """

   313

    Stores the Modbus parameter configuration into the

   314

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

   315

    """

   316

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   317

    SetParamFuncs  = _WebNodeList[WebNode_id]["SetParamFuncs"]

   318

   319

    for par_name in newconfig:

   320

        value = newconfig[par_name]

   321

        if value is not None:

   322

            SetParamFuncs[par_name](C_node_id, value)

   323

   324

   325

   326

   327

def _GetWebviewConfigurationValue(ctx, WebNode_id, argument):

   328

    """

   329

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

   330

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

   331

   332

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

   333

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

   334

    as a parameter.

   335

    """    

   336

    try:

   337

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

   338

    except Exception:

   339

        return ""

   340

   341

   342

   343

   344

def _updateWebInterface(WebNode_id):

   345

    """

   346

    Add/Remove buttons to/from the web interface depending on the current state

   347

       - If there is a saved state => add a delete saved state button

   348

    """

   349

   350

    config_hash = _WebNodeList[WebNode_id]["config_hash"]

   351

    config_name = _WebNodeList[WebNode_id]["config_name"]

   352

   353

    # Add a "Delete Saved Configuration" button if there is a saved configuration!

   354

    if _WebNodeList[WebNode_id]["SavedConfiguration"] is None:

   355

        _NS.ConfigurableSettings.delSettings("ModbusConfigDelSaved" + config_hash)

   356

    else:

   357

        def __OnButtonDel(**kwargs):

   358

            return OnButtonDel(WebNode_id = WebNode_id, **kwargs)

   359

   360

        _NS.ConfigurableSettings.addSettings(

   361

            "ModbusConfigDelSaved"      + config_hash,  # name (internal, may not contain spaces, ...)

   362

            _("Modbus Configuration: ") + config_name,  # description (user visible label)

   363

            [],                                         # fields  (empty, no parameters required!)

   364

            _("Delete Configuration Stored in Persistent Storage"), # button label

   365

            __OnButtonDel,                              # callback    

   366

            "ModbusConfigParm"          + config_hash)  # Add after entry xxxx

   367

   368

   369

   370

def OnButtonSave(**kwargs):

   371

    """

   372

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

   373

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

   374

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

   375

   376

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

   377

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

   378

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

   379

    """

   380

   381

    #_plcobj.LogMessage("Modbus web server extension::OnButtonSave()  Called")

   382

   383

    newConfig    = {}

   384

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

   385

    WebParamList = _WebNodeList[WebNode_id]["WebParamList"]

   386

   387

    for par_name, x1, x2, x3 in WebParamList:

   388

        value = kwargs.get(par_name, None)

   389

        if value is not None:

   390

            newConfig[par_name] = value

   391

   392

    # First check if configuration is OK.

   393

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

   394

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

   395

    #if not _CheckWebConfiguration(newConfig):

   396

    #    return

   397

   398

    # store to file the new configuration so that 

   399

    # we can recoup the configuration the next time the PLC

   400

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

   401

    _SetSavedConfiguration(WebNode_id, newConfig)

   402

   403

    # Configure PLC with the current Modbus parameters

   404

    _SetPLCConfiguration(WebNode_id, newConfig)

   405

   406

    # Update the viewable configuration

   407

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

   408

    # so we do not set it directly to newConfig

   409

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

   410

   411

    # File has just been created => Delete button must be shown on web interface!

   412

    _updateWebInterface(WebNode_id)

   413

   414

   415

   416

   417

def OnButtonDel(**kwargs):

   418

    """

   419

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

   420

    The function will delete the file containing the persistent

   421

    Modbus configution

   422

    """

   423

   424

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

   425

   426

    # Delete the file

   427

    _DelSavedConfiguration(WebNode_id)

   428

   429

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

   430

    new_config = _WebNodeList[WebNode_id]["DefaultConfiguration"]

   431

    _SetPLCConfiguration(WebNode_id, new_config)

   432

   433

    #Update the webviewconfiguration

   434

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = new_config

   435

   436

    # Reset SavedConfiguration

   437

    _WebNodeList[WebNode_id]["SavedConfiguration"] = None

   438

   439

    # File has just been deleted => Delete button on web interface no longer needed!

   440

    _updateWebInterface(WebNode_id)

   441

   442

   443

   444

   445

def OnButtonShowCur(**kwargs):

   446

    """

   447

    Function called when user clicks 'Show Current PLC Configuration' button in web interface

   448

    The function will load the current PLC configuration into the web form

   449

   450

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

   451

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

   452

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

   453

    """

   454

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

   455

   456

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

   457

   458

   459

   460

   461

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

   462

    """

   463

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

   464

    the configuration parameters of a specific Modbus plugin node.

   465

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

   466

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

   467

    node versions of the Get/Set functions)

   468

    """

   469

    WebNode_entry = {}

   470

   471

    # Get the config_name from the C code...

   472

    config_name = GetParamFuncs["config_name"](C_node_id)

   473

    # Get the addr_type from the C code...

   474

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

   475

    addr_type   = GetParamFuncs["addr_type"  ](C_node_id)   

   476

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

   477

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

   478

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

   479

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

   480

   481

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

   482

   483

    # Add the new entry to the global list

   484

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

   485

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

   486

    global _WebNodeList

   487

    _WebNodeList.append(WebNode_entry)

   488

    WebNode_id = len(_WebNodeList) - 1

   489

   490

    # store all WebNode relevant data for future reference

   491

    #

   492

    # Note that "WebParamList" will reference one of:

   493

    #  - TCPclient_parameters, TCPserver_parameters, RTUclient_parameters, RTUslave_parameters

   494

    WebNode_entry["C_node_id"    ] = C_node_id

   495

    WebNode_entry["config_name"  ] = config_name 

   496

    WebNode_entry["config_hash"  ] = config_hash

   497

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

   498

    WebNode_entry["GetParamFuncs"] = GetParamFuncs

   499

    WebNode_entry["SetParamFuncs"] = SetParamFuncs

   500

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

   501

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

   502

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

   503

   504

   505

    # Dictionary that contains the Modbus configuration currently being shown