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

    ("req_delay"        , _("Request Delay (ms)")    , ctypes.c_ulonglong, annotate.Integer )

   154

    ]

   155

   156

RTUclient_parameters = [                                                   

   157

    #    param. name       label                        ctype type         annotate type

   158

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

   159

    #                                                                      (annotate.String,

   160

    #                                                                       annotate.Integer, ...)

   161

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

   162

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

   163

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

   164

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

   165

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

   166

    ("req_delay"        , _("Request Delay (ms)")    , ctypes.c_ulonglong, annotate.Integer)

   167

    ]

   168

   169

TCPserver_parameters = [                                                   

   170

    #    param. name       label                        ctype type         annotate type

   171

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

   172

    #                                                                      (annotate.String,

   173

    #                                                                       annotate.Integer, ...)

   174

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

   175

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

   176

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

   177

    ]

   178

   179

RTUslave_parameters = [                                                   

   180

    #    param. name       label                        ctype type         annotate type

   181

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

   182

    #                                                                      (annotate.String,

   183

    #                                                                       annotate.Integer, ...)

   184

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

   185

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

   186

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

   187

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

   188

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

   189

    ]

   190

   191

   192

   193

   194

# Dictionary containing List of Web viewable parameters

   195

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

   196

# __modbus_get_ClientNode_addr_type()

   197

# __modbus_get_ServerNode_addr_type()

   198

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

   199

_client_WebParamListDict = {}

   200

_client_WebParamListDict["tcp"  ] = TCPclient_parameters

   201

_client_WebParamListDict["rtu"  ] = RTUclient_parameters

   202

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

   203

   204

_server_WebParamListDict = {}

   205

_server_WebParamListDict["tcp"  ] = TCPserver_parameters

   206

_server_WebParamListDict["rtu"  ] = RTUslave_parameters

   207

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

   208

   209

WebParamListDictDict = {}

   210

WebParamListDictDict['client'] = _client_WebParamListDict

   211

WebParamListDictDict['server'] = _server_WebParamListDict

   212

   213

   214

   215

   216

   217

   218

def _SetModbusSavedConfiguration(WebNode_id, newConfig):

   219

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

   220

    WebNode_entry = _WebNodeList[WebNode_id]

   221

   222

    if WebNode_entry["DefaultConfiguration"] == newConfig:

   223

   224

        _DelModbusSavedConfiguration(WebNode_id)

   225

        WebNode_entry["ModbusSavedConfiguration"] = None

   226

   227

    else:

   228

   229

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

   230

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

   231

        # when loading from file

   232

        save_info = {}

   233

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

   234

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

   235

        save_info["config"   ] = newConfig

   236

   237

        filename = WebNode_entry["filename"]

   238

   239

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

   240

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

   241

   242

        WebNode_entry["ModbusSavedConfiguration"] = newConfig

   243

   244

   245

   246

   247

def _DelModbusSavedConfiguration(WebNode_id):

   248

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

   249

    filename = _WebNodeList[WebNode_id]["filename"]

   250

   251

    if os.path.exists(filename):

   252

        os.remove(filename)

   253

   254

   255

   256

   257

def _GetModbusSavedConfiguration(WebNode_id):

   258

    """

   259

    Returns a dictionary containing the Modbus parameter configuration

   260

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

   261

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

   262

    addr_type of the WebNode_id), then return None

   263

    """

   264

    filename = _WebNodeList[WebNode_id]["filename"]

   265

    try:

   266

        #if os.path.isfile(filename):

   267

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

   268

    except Exception:    

   269

        return None

   270

   271

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

   272

        return None

   273

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

   274

        return None

   275

    if "config" not in save_info:

   276

        return None

   277

   278

    saved_config = save_info["config"]

   279

   280

    #if _CheckConfiguration(saved_config):

   281

    #    return saved_config

   282

    #else:

   283

    #    return None

   284

   285

    return saved_config

   286

   287

   288

   289

def _GetModbusPLCConfiguration(WebNode_id):

   290

    """

   291

    Returns a dictionary containing the current Modbus parameter configuration

   292

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

   293

    """

   294

    current_config = {}

   295

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   296

    WebParamList   = _WebNodeList[WebNode_id]["WebParamList"]

   297

    GetParamFuncs  = _WebNodeList[WebNode_id]["GetParamFuncs"]

   298

   299

    for par_name, x1, x2, x3 in WebParamList:

   300

        value = GetParamFuncs[par_name](C_node_id)

   301

        if value is not None:

   302

            current_config[par_name] = value

   303

   304

    return current_config

   305

   306

   307

   308

def _SetModbusPLCConfiguration(WebNode_id, newconfig):

   309

    """

   310

    Stores the Modbus parameter configuration into the

   311

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

   312

    """

   313

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   314

    SetParamFuncs  = _WebNodeList[WebNode_id]["SetParamFuncs"]

   315

   316

    for par_name in newconfig:

   317

        value = newconfig[par_name]

   318

        if value is not None:

   319

            SetParamFuncs[par_name](C_node_id, value)

   320

   321

   322

   323

   324

def _GetModbusWebviewConfigurationValue(ctx, WebNode_id, argument):

   325

    """

   326

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

   327

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

   328

   329

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

   330

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

   331

    as a parameter.

   332

    """    

   333

    try:

   334

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

   335

    except Exception:

   336

        return ""

   337

   338

   339

   340

def OnModbusButtonSave(**kwargs):

   341

    """

   342

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

   343

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

   344

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

   345

   346

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

   347

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

   348

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

   349

    """

   350

   351

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

   352

   353

    newConfig    = {}

   354

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

   355

    WebParamList = _WebNodeList[WebNode_id]["WebParamList"]

   356

   357

    for par_name, x1, x2, x3 in WebParamList:

   358

        value = kwargs.get(par_name, None)

   359

        if value is not None:

   360

            newConfig[par_name] = value

   361

   362

    # First check if configuration is OK.

   363

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

   364

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

   365

    #if not _CheckWebConfiguration(newConfig):

   366

    #    return

   367

   368

    # store to file the new configuration so that 

   369

    # we can recoup the configuration the next time the PLC

   370

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

   371

    _SetModbusSavedConfiguration(WebNode_id, newConfig)

   372

   373

    # Configure PLC with the current Modbus parameters

   374

    _SetModbusPLCConfiguration(WebNode_id, newConfig)

   375

   376

    # Update the viewable configuration

   377

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

   378

    # so we do not set it directly to newConfig

   379

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

   380

   381

   382

   383

def OnModbusButtonReset(**kwargs):

   384

    """

   385

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

   386

    The function will delete the file containing the persistent

   387

    Modbus configution

   388

    """

   389

   390

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

   391

   392

    # Delete the file

   393

    _DelModbusSavedConfiguration(WebNode_id)

   394

   395

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

   396

    new_config = _WebNodeList[WebNode_id]["DefaultConfiguration"]

   397

    _SetModbusPLCConfiguration(WebNode_id, new_config)

   398

   399

    #Update the webviewconfiguration

   400

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = new_config

   401

   402

    # Reset ModbusSavedConfiguration

   403

    _WebNodeList[WebNode_id]["ModbusSavedConfiguration"] = None

   404

   405

   406

   407

   408

   409

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

   410

    """

   411

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

   412

    the configuration parameters of a specific Modbus plugin node.

   413

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

   414

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

   415

    node versions of the Get/Set functions)

   416

    """

   417

    WebNode_entry = {}

   418

   419

    # Get the config_name from the C code...

   420

    config_name = GetParamFuncs["config_name"](C_node_id)

   421

    # Get the addr_type from the C code...

   422

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

   423

    addr_type   = GetParamFuncs["addr_type"  ](C_node_id)   

   424

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

   425

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

   426

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

   427

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

   428

   429

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

   430

   431

    # Add the new entry to the global list

   432

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

   433

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

   434

    global _WebNodeList

   435

    _WebNodeList.append(WebNode_entry)

   436

    WebNode_id = len(_WebNodeList) - 1

   437

   438

    # store all WebNode relevant data for future reference

   439

    #

   440

    # Note that "WebParamList" will reference one of:

   441

    #  - TCPclient_parameters, TCPserver_parameters, RTUclient_parameters, RTUslave_parameters

   442

    WebNode_entry["C_node_id"    ] = C_node_id

   443

    WebNode_entry["config_name"  ] = config_name 

   444

    WebNode_entry["config_hash"  ] = config_hash

   445

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

   446

    WebNode_entry["GetParamFuncs"] = GetParamFuncs

   447

    WebNode_entry["SetParamFuncs"] = SetParamFuncs

   448

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

   449

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

   450

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

   451

   452

   453

    # Dictionary that contains the Modbus configuration currently being shown

   454

    # on the web interface

   455

    # This configuration will almost always be identical to the current

   456

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

   457

    # C variables in the .so file).

   458

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

   459

    # configuration when the user edits the configuration, and when

   460

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

   461

    WebNode_entry["WebviewConfiguration"] = None

   462

   463

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

   464

    # hardcoded in the C file

   465

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

   466

    WebNode_entry["DefaultConfiguration"] = _GetModbusPLCConfiguration(WebNode_id)

   467

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

   468

   469

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

   470

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

   471

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

   472

    SavedConfig = _GetModbusSavedConfiguration(WebNode_id)

   473

    WebNode_entry["ModbusSavedConfiguration"] = SavedConfig

   474

   475

    if SavedConfig is not None:

   476

        _SetModbusPLCConfiguration(WebNode_id, SavedConfig)

   477

        WebNode_entry["WebviewConfiguration"] = SavedConfig

   478

   479

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

   480

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

   481

    # Note: We transform every parameter into a string

   482

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

   483

    #           accept the default value as an Integer python object

   484

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

   485

    #           always handled as strings.

   486

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

   487

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

   488

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

   489

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

   490

    def __GetWebviewConfigurationValue(ctx, argument):

   491

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

   492

   493

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

   494

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

   495

   496

    # Configure the web interface to include the Modbus config parameters

   497

    def __OnButtonSave(**kwargs):

   498

        OnModbusButtonSave(WebNode_id=WebNode_id, **kwargs)

   499

   500

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