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

# Will contain references to the C functions 

    65

# (implemented in beremiz/modbus/mb_runtime.c)

    66

# used to get/set the Modbus specific configuration paramters

    67

GetParamFuncs = {}

    68

SetParamFuncs = {}

    69

    70

    71

# List of all TCP clients configured in the loaded PLC (i.e. the .so file loaded into memory)

    72

# Each entry will be a dictionary. See _Add_TCP_Client() for the data structure details...

    73

_TCPclient_list = []

    74

    75

    76

    77

    78

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

    79

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

    80

General_parameters = [

    81

    #    param. name       label                        ctype type         annotate type

    82

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

    83

    #                                                                      (annotate.String,

    84

    #                                                                       annotate.Integer, ...)

    85

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

    86

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

    87

    ]                                                                      

    88

    89

TCPclient_parameters = [                                                   

    90

    #    param. name       label                        ctype type         annotate type

    91

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

    92

    #                                                                      (annotate.String,

    93

    #                                                                       annotate.Integer, ...)

    94

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

    95

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

    96

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

    97

    ]

    98

    99

RTUclient_parameters = [                                                   

   100

    #    param. name       label                        ctype type         annotate type

   101

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

   102

    #                                                                      (annotate.String,

   103

    #                                                                       annotate.Integer, ...)

   104

    ("device"           , _("Serial Port")           , ctypes.c_char_p,    annotate.String),

   105

    ("baud"             , _("Baud Rate")             , ctypes.c_int,       annotate.Integer),

   106

    ("parity"           , _("Parity")                , ctypes.c_int,       annotate.Integer),

   107

    ("stop_bits"        , _("Stop Bits")             , ctypes.c_int,       annotate.Integer),

   108

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

   109

    ]

   110

   111

   112

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

   113

# __modbus_get_ClientNode_addr_type()

   114

# __modbus_get_ServerNode_addr_type()

   115

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

   116

_client_parameters = {}

   117

_client_parameters["tcp"  ] = TCPclient_parameters

   118

_client_parameters["rtu"  ] = RTUclient_parameters

   119

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

   120

   121

   122

#def _CheckPortnumber(port_number):

   123

#    """ check validity of the port number """

   124

#    try:

   125

#        portnum = int(port_number)

   126

#        if (portnum < 0) or (portnum > 65535):

   127

#           raise Exception

   128

#    except Exception:    

   129

#        return False

   130

#        

   131

#    return True

   132

   133

   134

   135

   136

#def _CheckConfiguration(BACnetConfig):

   137

#    res = True    

   138

#    res = res and _CheckPortnumber(BACnetConfig["port_number"])

   139

#    res = res and _CheckDeviceID  (BACnetConfig["device_id"])

   140

#    return res

   141

   142

   143

   144

#def _CheckWebConfiguration(BACnetConfig):

   145

#    res = True

   146

#    

   147

#    # check the port number

   148

#    if not _CheckPortnumber(BACnetConfig["port_number"]):

   149

#        raise annotate.ValidateError(

   150

#            {"port_number": "Invalid port number: " + str(BACnetConfig["port_number"])},

   151

#            _("Modbus configuration error:"))

   152

#        res = False

   153

#    

   154

#    if not _CheckDeviceID(BACnetConfig["device_id"]):

   155

#        raise annotate.ValidateError(

   156

#            {"device_id": "Invalid device ID: " + str(BACnetConfig["device_id"])},

   157

#            _("Modbus configuration error:"))

   158

#        res = False

   159

#        

   160

#    return res

   161

   162

   163

   164

   165

   166

   167

def _SetSavedConfiguration(node_id, newConfig):

   168

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

   169

   170

    filename = _TCPclient_list[node_id]["filename"]

   171

   172

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

   173

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

   174

   175

    _TCPclient_list[node_id]["SavedConfiguration"] = newConfig

   176

   177

   178

   179

   180

def _DelSavedConfiguration(node_id):

   181

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

   182

    filename = _TCPclient_list[node_id]["filename"]

   183

   184

    if os.path.exists(filename):

   185

        os.remove(filename)

   186

   187

   188

   189

   190

def _GetSavedConfiguration(node_id):

   191

    """

   192

    Returns a dictionary containing the Modbus parameter configuration

   193

    that was last saved to file. If no file exists, then return None

   194

    """

   195

    filename = _TCPclient_list[node_id]["filename"]

   196

    try:

   197

        #if os.path.isfile(filename):

   198

        saved_config = json.load(open(filename))

   199

    except Exception:    

   200

        return None

   201

   202

    #if _CheckConfiguration(saved_config):

   203

    #    return saved_config

   204

    #else:

   205

    #    return None

   206

   207

    return saved_config

   208

   209

   210

   211

def _GetPLCConfiguration(node_id):

   212

    """

   213

    Returns a dictionary containing the current Modbus parameter configuration

   214

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

   215

    """

   216

    current_config = {}

   217

    addr_type = _TCPclient_list[node_id]["addr_type"]

   218

   219

    for par_name, x1, x2, x3 in _client_parameters[addr_type]:

   220

        value = GetParamFuncs[par_name](node_id)

   221

        if value is not None:

   222

            current_config[par_name] = value

   223

   224

    return current_config

   225

   226

   227

   228

def _SetPLCConfiguration(node_id, newconfig):

   229

    """

   230

    Stores the Modbus parameter configuration into the

   231

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

   232

    """

   233

    addr_type = _TCPclient_list[node_id]["addr_type"]

   234

   235

    for par_name in newconfig:

   236

        value = newconfig[par_name]

   237

        if value is not None:

   238

            SetParamFuncs[par_name](node_id, value)

   239

   240

   241

   242

   243

def _GetWebviewConfigurationValue(ctx, node_id, argument):

   244

    """

   245

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

   246

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

   247

   248

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

   249

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

   250

    as a parameter.

   251

    """

   252

    try:

   253

        return _TCPclient_list[node_id]["WebviewConfiguration"][argument.name]

   254

    except Exception:

   255

        return ""

   256

   257

   258

   259

   260

def _updateWebInterface(node_id):

   261

    """

   262

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

   263

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

   264

    """

   265

   266

    config_hash = _TCPclient_list[node_id]["config_hash"]

   267

    config_name = _TCPclient_list[node_id]["config_name"]

   268

   269

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

   270

    if _TCPclient_list[node_id]["SavedConfiguration"] is None:

   271

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

   272

    else:

   273

        def __OnButtonDel(**kwargs):

   274

            return OnButtonDel(node_id = node_id, **kwargs)

   275

   276

        _NS.ConfigurableSettings.addSettings(

   277

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

   278

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

   279

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

   280

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

   281

            __OnButtonDel,                              # callback    

   282

            "ModbusConfigParm"          + config_hash)  # Add after entry xxxx

   283

   284

   285

   286

def OnButtonSave(**kwargs):

   287

    """

   288

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

   289

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

   290

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

   291

   292

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

   293

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

   294

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

   295

    """

   296

   297

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

   298

   299

    newConfig = {}

   300

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

   301

    addr_type = _TCPclient_list[node_id]["addr_type"]

   302

   303

    for par_name, x1, x2, x3 in _client_parameters[addr_type]:

   304

        value = kwargs.get(par_name, None)

   305

        if value is not None:

   306

            newConfig[par_name] = value

   307

   308

    _TCPclient_list[node_id]["WebviewConfiguration"] = newConfig

   309

   310

    # First check if configuration is OK.

   311

    ## TODO...

   312

    #if not _CheckWebConfiguration(newConfig):

   313

    #    return

   314

   315

    # store to file the new configuration so that 

   316

    # we can recoup the configuration the next time the PLC

   317

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

   318

    _SetSavedConfiguration(node_id, newConfig)

   319

   320

    # Configure PLC with the current Modbus parameters

   321

    _SetPLCConfiguration(node_id, newConfig)

   322

   323

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

   324

    _updateWebInterface(node_id)

   325

   326

   327

   328

   329

def OnButtonDel(**kwargs):

   330

    """

   331

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

   332

    The function will delete the file containing the persistent

   333

    Modbus configution

   334

    """

   335

   336

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

   337

   338

    # Delete the file

   339

    _DelSavedConfiguration(node_id)

   340

   341

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

   342

    new_config = _TCPclient_list[node_id]["DefaultConfiguration"]

   343

    _SetPLCConfiguration(node_id, new_config)

   344

   345

    #Update the webviewconfiguration

   346

    _TCPclient_list[node_id]["WebviewConfiguration"] = new_config

   347

   348

    # Reset SavedConfiguration

   349

    _TCPclient_list[node_id]["SavedConfiguration"] = None

   350

   351

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

   352

    _updateWebInterface(node_id)

   353

   354

   355

   356

   357

def OnButtonShowCur(**kwargs):

   358

    """

   359

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

   360

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

   361

   362

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

   363

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

   364

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

   365

    """

   366

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

   367

   368

    _TCPclient_list[node_id]["WebviewConfiguration"] = _GetPLCConfiguration(node_id)

   369

   370

   371

   372

   373

def _Load_TCP_Client(node_id):

   374

    TCPclient_entry = {}

   375

   376

    config_name = GetParamFuncs["config_name"](node_id)

   377

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

   378

    addr_type   = GetParamFuncs["addr_type"  ](node_id)   

   379

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

   380

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

   381

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

   382

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

   383

   384

    _plcobj.LogMessage("Modbus web server extension::_Load_TCP_Client("+str(node_id)+") config_name="+config_name)

   385

   386

    # Add the new entry to the global list

   387

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

   388

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

   389

    global _TCPclient_list

   390

    _TCPclient_list.append(TCPclient_entry)

   391

   392

    # store all node_id relevant data for future reference

   393

    TCPclient_entry["node_id"     ] = node_id

   394

    TCPclient_entry["config_name" ] = config_name 

   395

    TCPclient_entry["addr_type"   ] = addr_type

   396

    TCPclient_entry["config_hash" ] = config_hash

   397

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

   398

   399

    # Dictionary that contains the Modbus configuration currently being shown

   400

    # on the web interface

   401

    # This configuration will almost always be identical to the current

   402

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

   403

    # C variables in the .so file).

   404

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

   405

    # configuration when the user edits the configuration, and when

   406

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

   407

    TCPclient_entry["WebviewConfiguration"] = None

   408

   409

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

   410

    # hardcoded in the C file

   411

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

   412

    TCPclient_entry["DefaultConfiguration"] = _GetPLCConfiguration(node_id)

   413

    TCPclient_entry["WebviewConfiguration"] = TCPclient_entry["DefaultConfiguration"]

   414

   415

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

   416

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

   417

    # web interface (only shown if _SavedConfiguration is not None)

   418

    SavedConfig = _GetSavedConfiguration(node_id)

   419

    TCPclient_entry["SavedConfiguration"] = SavedConfig

   420

   421

    if SavedConfig is not None:

   422

        _SetPLCConfiguration(node_id, SavedConfig)

   423

        TCPclient_entry["WebviewConfiguration"] = SavedConfig

   424

   425

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

   426

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

   427

    def __GetWebviewConfigurationValue(ctx, argument):

   428

        return _GetWebviewConfigurationValue(ctx, node_id, argument)

   429

   430

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

   431

                    for name, web_label, c_dtype, web_dtype in _client_parameters[addr_type]]

   432

   433

    # Configure the web interface to include the Modbus config parameters

   434

    def __OnButtonSave(**kwargs):

   435

        OnButtonSave(node_id=node_id, **kwargs)

   436

   437

    _NS.ConfigurableSettings.addSettings(

   438

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

   439

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

   440

        webFormInterface,                              # fields

   441

        _("Save Configuration to Persistent Storage"), # button label

   442

        __OnButtonSave)                                # callback   

   443

   444

    # Add a "View Current Configuration" button 

   445

    def __OnButtonShowCur(**kwargs):

   446

        OnButtonShowCur(node_id=node_id, **kwargs)

   447

   448

    _NS.ConfigurableSettings.addSettings(

   449

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

   450

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

   451

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

   452

        _("Show Current PLC Configuration"),       # button label

   453

        __OnButtonShowCur)                         # callback    

   454

   455

    # Add the Delete button to the web interface, if required

   456

    _updateWebInterface(node_id)

   457

   458

   459

   460

   461

def OnLoadPLC():

   462

    """

   463

    Callback function, called (by PLCObject.py) when a new PLC program

   464

    (i.e. XXX.so file) is transfered to the PLC runtime

   465

    and loaded into memory

   466

    """

   467

   468

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

   469

   470

    if _plcobj.PLClibraryHandle is None:

   471

        # PLC was loaded but we don't have access to the library of compiled code (.so lib)?

   472

        # Hmm... This shold never occur!! 

   473

        return  

   474

   475

    # Get the number of Modbus Client and Servers (Modbus plugin)

   476

    # configured in the currently loaded PLC project (i.e., the .so file)

   477

    # If the "__modbus_plugin_client_node_count" 

   478

    # or the "__modbus_plugin_server_node_count" C variables 

   479

    # are not present in the .so file we conclude that the currently loaded 

   480

    # PLC does not have the Modbus plugin included (situation (2b) described above init())

   481

    try:

   482

        client_count = ctypes.c_int.in_dll(_plcobj.PLClibraryHandle, "__modbus_plugin_client_node_count").value

   483

        server_count = ctypes.c_int.in_dll(_plcobj.PLClibraryHandle, "__modbus_plugin_server_node_count").value

   484

    except Exception:

   485

        # Loaded PLC does not have the Modbus plugin => nothing to do

   486

        #   (i.e. do _not_ configure and make available the Modbus web interface)

   487

        return

   488

   489

    if client_count < 0: client_count = 0

   490

    if server_count < 0: server_count = 0

   491

   492

    if (client_count == 0) and (server_count == 0):

   493

        # The Modbus plugin in the loaded PLC does not have any client and servers configured

   494

        #  => nothing to do (i.e. do _not_ configure and make available the Modbus web interface)

   495

        return

   496

   497

    # Map the get/set functions (written in C code) we will be using to get/set the configuration parameters

   498

    for name, web_label, c_dtype, web_dtype in TCPclient_parameters + RTUclient_parameters + General_parameters:

   499

        GetParamFuncName             = "__modbus_get_ClientNode_" + name        

   500

        GetParamFuncs[name]          = getattr(_plcobj.PLClibraryHandle, GetParamFuncName)

   501

        GetParamFuncs[name].restype  = c_dtype

   502

        GetParamFuncs[name].argtypes = [ctypes.c_int]

   503

   504

    for name, web_label, c_dtype, web_dtype in TCPclient_parameters + RTUclient_parameters:

   505

        SetParamFuncName             = "__modbus_set_ClientNode_" + name

   506

        SetParamFuncs[name]          = getattr(_plcobj.PLClibraryHandle, SetParamFuncName)

   507

        SetParamFuncs[name].restype  = None

   508

        SetParamFuncs[name].argtypes = [ctypes.c_int, c_dtype]

   509

   510

    for node_id in range(client_count):

   511

        _Load_TCP_Client(node_id)

   512

   513

   514

   515

   516

   517

   518

def OnUnLoadPLC():

   519

    """

   520

    # Callback function, called (by PLCObject.py) when a PLC program is unloaded from memory

   521

    """

   522

   523

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

   524

   525

    # Delete the Modbus specific web interface extensions

   526

    # (Safe to ask to delete, even if it has not been added!)

   527

    global _TCPclient_list    

   528

    for TCPclient_entry in _TCPclient_list:

   529

        config_hash = TCPclient_entry["config_hash"]

   530

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