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_ulonglong, 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 _SetSavedConfiguration(WebNode_id, newConfig):

   217

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

   218

   219

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

   220

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

   221

    # when loading from file

   222

    save_info = {}

   223

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

   224

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

   225

    save_info["config"   ] = newConfig

   226

   227

    filename = _WebNodeList[WebNode_id]["filename"]

   228

   229

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

   230

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

   231

   232

    _WebNodeList[WebNode_id]["SavedConfiguration"] = newConfig

   233

   234

   235

   236

   237

def _DelSavedConfiguration(WebNode_id):

   238

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

   239

    filename = _WebNodeList[WebNode_id]["filename"]

   240

   241

    if os.path.exists(filename):

   242

        os.remove(filename)

   243

   244

   245

   246

   247

def _GetSavedConfiguration(WebNode_id):

   248

    """

   249

    Returns a dictionary containing the Modbus parameter configuration

   250

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

   251

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

   252

    addr_type of the WebNode_id), then return None

   253

    """

   254

    filename = _WebNodeList[WebNode_id]["filename"]

   255

    try:

   256

        #if os.path.isfile(filename):

   257

        save_info = json.load(open(filename))

   258

    except Exception:    

   259

        return None

   260

   261

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

   262

        return None

   263

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

   264

        return None

   265

    if "config" not in save_info:

   266

        return None

   267

   268

    saved_config = save_info["config"]

   269

   270

    #if _CheckConfiguration(saved_config):

   271

    #    return saved_config

   272

    #else:

   273

    #    return None

   274

   275

    return saved_config

   276

   277

   278

   279

def _GetPLCConfiguration(WebNode_id):

   280

    """

   281

    Returns a dictionary containing the current Modbus parameter configuration

   282

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

   283

    """

   284

    current_config = {}

   285

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   286

    WebParamList   = _WebNodeList[WebNode_id]["WebParamList"]

   287

    GetParamFuncs  = _WebNodeList[WebNode_id]["GetParamFuncs"]

   288

   289

    for par_name, x1, x2, x3 in WebParamList:

   290

        value = GetParamFuncs[par_name](C_node_id)

   291

        if value is not None:

   292

            current_config[par_name] = value

   293

   294

    return current_config

   295

   296

   297

   298

def _SetPLCConfiguration(WebNode_id, newconfig):

   299

    """

   300

    Stores the Modbus parameter configuration into the

   301

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

   302

    """

   303

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   304

    SetParamFuncs  = _WebNodeList[WebNode_id]["SetParamFuncs"]

   305

   306

    for par_name in newconfig:

   307

        value = newconfig[par_name]

   308

        if value is not None:

   309

            SetParamFuncs[par_name](C_node_id, value)

   310

   311

   312

   313

   314

def _GetWebviewConfigurationValue(ctx, WebNode_id, argument):

   315

    """

   316

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

   317

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

   318

   319

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

   320

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

   321

    as a parameter.

   322

    """    

   323

    try:

   324

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

   325

    except Exception:

   326

        return ""

   327

   328

   329

   330

def OnButtonSave(**kwargs):

   331

    """

   332

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

   333

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

   334

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

   335

   336

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

   337

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

   338

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

   339

    """

   340

   341

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

   342

   343

    newConfig    = {}

   344

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

   345

    WebParamList = _WebNodeList[WebNode_id]["WebParamList"]

   346

   347

    for par_name, x1, x2, x3 in WebParamList:

   348

        value = kwargs.get(par_name, None)

   349

        if value is not None:

   350

            newConfig[par_name] = value

   351

   352

    # First check if configuration is OK.

   353

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

   354

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

   355

    #if not _CheckWebConfiguration(newConfig):

   356

    #    return

   357

   358

    # store to file the new configuration so that 

   359

    # we can recoup the configuration the next time the PLC

   360

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

   361

    _SetSavedConfiguration(WebNode_id, newConfig)

   362

   363

    # Configure PLC with the current Modbus parameters

   364

    _SetPLCConfiguration(WebNode_id, newConfig)

   365

   366

    # Update the viewable configuration

   367

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

   368

    # so we do not set it directly to newConfig

   369

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

   370

   371

   372

   373

def OnButtonReset(**kwargs):

   374

    """

   375

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

   376

    The function will delete the file containing the persistent

   377

    Modbus configution

   378

    """

   379

   380

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

   381

   382

    # Delete the file

   383

    _DelSavedConfiguration(WebNode_id)

   384

   385

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

   386

    new_config = _WebNodeList[WebNode_id]["DefaultConfiguration"]

   387

    _SetPLCConfiguration(WebNode_id, new_config)

   388

   389

    #Update the webviewconfiguration

   390

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = new_config

   391

   392

    # Reset SavedConfiguration

   393

    _WebNodeList[WebNode_id]["SavedConfiguration"] = None

   394

   395

   396

   397

   398

   399

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

   400

    """

   401

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

   402

    the configuration parameters of a specific Modbus plugin node.

   403

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

   404

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

   405

    node versions of the Get/Set functions)

   406

    """

   407

    WebNode_entry = {}

   408

   409

    # Get the config_name from the C code...

   410

    config_name = GetParamFuncs["config_name"](C_node_id)

   411

    # Get the addr_type from the C code...

   412

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

   413

    addr_type   = GetParamFuncs["addr_type"  ](C_node_id)   

   414

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

   415

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

   416

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

   417

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

   418

   419

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

   420

   421

    # Add the new entry to the global list

   422

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

   423

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

   424

    global _WebNodeList

   425

    _WebNodeList.append(WebNode_entry)

   426

    WebNode_id = len(_WebNodeList) - 1

   427

   428

    # store all WebNode relevant data for future reference

   429

    #

   430

    # Note that "WebParamList" will reference one of:

   431

    #  - TCPclient_parameters, TCPserver_parameters, RTUclient_parameters, RTUslave_parameters

   432

    WebNode_entry["C_node_id"    ] = C_node_id

   433

    WebNode_entry["config_name"  ] = config_name 

   434

    WebNode_entry["config_hash"  ] = config_hash

   435

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

   436

    WebNode_entry["GetParamFuncs"] = GetParamFuncs

   437

    WebNode_entry["SetParamFuncs"] = SetParamFuncs

   438

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

   439

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

   440

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

   441

   442

   443

    # Dictionary that contains the Modbus configuration currently being shown

   444

    # on the web interface

   445

    # This configuration will almost always be identical to the current

   446

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

   447

    # C variables in the .so file).

   448

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

   449

    # configuration when the user edits the configuration, and when

   450

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

   451

    WebNode_entry["WebviewConfiguration"] = None

   452

   453

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

   454

    # hardcoded in the C file

   455

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

   456

    WebNode_entry["DefaultConfiguration"] = _GetPLCConfiguration(WebNode_id)

   457

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

   458

   459

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

   460

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

   461

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

   462

    SavedConfig = _GetSavedConfiguration(WebNode_id)

   463

    WebNode_entry["SavedConfiguration"] = SavedConfig

   464

   465

    if SavedConfig is not None:

   466

        _SetPLCConfiguration(WebNode_id, SavedConfig)

   467

        WebNode_entry["WebviewConfiguration"] = SavedConfig

   468

   469

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

   470

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

   471

    # Note: We transform every parameter into a string

   472

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

   473

    #           accept the default value as an Integer python object

   474

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

   475

    #           always handled as strings.

   476

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

   477

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

   478

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

   479

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

   480

    def __GetWebviewConfigurationValue(ctx, argument):

   481

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

   482

   483

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

   484

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

   485

   486

    # Configure the web interface to include the Modbus config parameters

   487

    def __OnButtonSave(**kwargs):

   488

        OnButtonSave(WebNode_id=WebNode_id, **kwargs)

   489

   490

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

   491

   492

    WebSettings.addSettings(

   493

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

   494

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

   495

        webFormInterface,                              # fields

   496

        _("Apply"), # button label

   497

        __OnButtonSave)                                # callback   

   498

   499

    def __OnButtonReset(**kwargs):

   500

        return OnButtonReset(WebNode_id = WebNode_id, **kwargs)

   501

   502