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

# The parameter coerce functions referenced in the TCPclient_parameters etc. lists.

   129

# These functions check wether the parameter has a legal value (i.e. they validate the parameter),

   130

# and if not changes it to the closest legal value (i.e. coerces the parameter value to a legal value)

   131

   132

def _coerce_comm_period(value):

   133

    # Period may not be negative value

   134

    if (value < 0):

   135

        value = 0

   136

    return value

   137

   138

def _coerce_req_delay(value):

   139

    # Request delay may not be negative value

   140

    # (i.e. delay between any two consecutive requests sent by a Beremiz RTU master or TCP client)

   141

    if (value < 0):

   142

        value = 0

   143

    return value

   144

   145

   146

   147

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

   148

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

   149

#

   150

# The annotate type entry is used to tell the web server the type of data entry widget to use.

   151

# (see the file twisted/nevow/formless/annotate.py for list of options)

   152

# Unfortunately an unsigned integer option does not exist.

   153

General_parameters = [

   154

    #    param. name       label                        ctype type         annotate type            Coerce

   155

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

   156

    #                                                                      (annotate.String,

   157

    #                                                                       annotate.Integer, ...)

   158

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

   159

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

   160

    ]                                                                      

   161

   162

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

   163

# on the web interface.

   164

TCPclient_parameters = [                                                   

   165

    #    param. name       label                        ctype type         annotate type            Coerce

   166

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

   167

    #                                                                      (annotate.String,

   168

    #                                                                       annotate.Integer, ...)

   169

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

   170

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

   171

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

   172

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

   173

    ]

   174

   175

RTUclient_parameters = [                                                   

   176

    #    param. name       label                        ctype type         annotate type            Coerce

   177

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

   178

    #                                                                      (annotate.String,

   179

    #                                                                       annotate.Integer, ...)

   180

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

   181

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

   182

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

   183

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

   184

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

   185

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

   186

    ]

   187

   188

TCPserver_parameters = [                                                   

   189

    #    param. name       label                        ctype type         annotate type            Coerce

   190

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

   191

    #                                                                      (annotate.String,

   192

    #                                                                       annotate.Integer, ...)

   193

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

   194

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

   195

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

   196

    ]

   197

   198

RTUslave_parameters = [                                                   

   199

    #    param. name       label                        ctype type         annotate type            Coerce

   200

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

   201

    #                                                                      (annotate.String,

   202

    #                                                                       annotate.Integer, ...)

   203

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

   204

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

   205

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

   206

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

   207

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

   208

    ]

   209

   210

   211

   212

   213

# Dictionary containing List of Web viewable parameters

   214

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

   215

# __modbus_get_ClientNode_addr_type()

   216

# __modbus_get_ServerNode_addr_type()

   217

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

   218

_client_WebParamListDict = {}

   219

_client_WebParamListDict["tcp"  ] = TCPclient_parameters

   220

_client_WebParamListDict["rtu"  ] = RTUclient_parameters

   221

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

   222

   223

_server_WebParamListDict = {}

   224

_server_WebParamListDict["tcp"  ] = TCPserver_parameters

   225

_server_WebParamListDict["rtu"  ] = RTUslave_parameters

   226

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

   227

   228

WebParamListDictDict = {}

   229

WebParamListDictDict['client'] = _client_WebParamListDict

   230

WebParamListDictDict['server'] = _server_WebParamListDict

   231

   232

   233

   234

   235

def _SetModbusSavedConfiguration(WebNode_id, newConfig):

   236

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

   237

    WebNode_entry = _WebNodeList[WebNode_id]

   238

   239

    if WebNode_entry["DefaultConfiguration"] == newConfig:

   240

   241

        _DelModbusSavedConfiguration(WebNode_id)

   242

        WebNode_entry["ModbusSavedConfiguration"] = None

   243

   244

    else:

   245

   246

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

   247

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

   248

        # when loading from file

   249

        save_info = {}

   250

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

   251

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

   252

        save_info["config"   ] = newConfig

   253

   254

        filename = WebNode_entry["filename"]

   255

   256

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

   257

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

   258

   259

        WebNode_entry["ModbusSavedConfiguration"] = newConfig

   260

   261

   262

   263

   264

def _DelModbusSavedConfiguration(WebNode_id):

   265

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

   266

    filename = _WebNodeList[WebNode_id]["filename"]

   267

   268

    if os.path.exists(filename):

   269

        os.remove(filename)

   270

   271

   272

   273

   274

def _GetModbusSavedConfiguration(WebNode_id):

   275

    """

   276

    Returns a dictionary containing the Modbus parameter configuration

   277

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

   278

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

   279

    addr_type of the WebNode_id), then return None

   280

    """

   281

    filename = _WebNodeList[WebNode_id]["filename"]

   282

    try:

   283

        #if os.path.isfile(filename):

   284

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

   285

    except Exception:    

   286

        return None

   287

   288

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

   289

        return None

   290

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

   291

        return None

   292

    if "config" not in save_info:

   293

        return None

   294

   295

    saved_config = save_info["config"]

   296

   297

    #if _CheckConfiguration(saved_config):

   298

    #    return saved_config

   299

    #else:

   300

    #    return None

   301

   302

    return saved_config

   303

   304

   305

   306

def _GetModbusPLCConfiguration(WebNode_id):

   307

    """

   308

    Returns a dictionary containing the current Modbus parameter configuration

   309

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

   310

    """

   311

    current_config = {}

   312

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   313

    WebParamList   = _WebNodeList[WebNode_id]["WebParamList"]

   314

    GetParamFuncs  = _WebNodeList[WebNode_id]["GetParamFuncs"]

   315

   316

    for WebParamListEntry in WebParamList:

   317

        par_name = WebParamListEntry[0]

   318

        value = GetParamFuncs[par_name](C_node_id)

   319

        if value is not None:

   320

            current_config[par_name] = value

   321

   322

    return current_config

   323

   324

   325

   326

def _SetModbusPLCConfiguration(WebNode_id, newconfig):

   327

    """

   328

    Stores the Modbus parameter configuration into the

   329

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

   330

    """

   331

    C_node_id      = _WebNodeList[WebNode_id]["C_node_id"]

   332

    SetParamFuncs  = _WebNodeList[WebNode_id]["SetParamFuncs"]

   333

   334

    for par_name in newconfig:

   335

        value = newconfig[par_name]

   336

        if value is not None:

   337

            SetParamFuncs[par_name](C_node_id, value)

   338

   339

   340

   341

   342

def _GetModbusWebviewConfigurationValue(ctx, WebNode_id, argument):

   343

    """

   344

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

   345

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

   346

   347

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

   348

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

   349

    as a parameter.

   350

    """    

   351

    try:

   352

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

   353

    except Exception:

   354

        return ""

   355

   356

   357

def _CoerceConfigurationValues(WebNode_id, config):

   358

    """

   359

    Coerces any incorrect value in the passed configuration

   360

    to the nearest correct value.

   361

    For example, negative times in delay paramater are changed to 0, etc...

   362

    """

   363

    CoerceParamFuncs  = _WebNodeList[WebNode_id]["CoerceParamFuncs"]

   364

   365

    for par_name in config:

   366

        CoerceFunction = CoerceParamFuncs[par_name]

   367

        if (config[par_name] is not None) and (CoerceFunction is not None):

   368

            config[par_name] = CoerceFunction(config[par_name])

   369

   370

   371

   372

def OnModbusButtonSave(**kwargs):

   373

    """

   374

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

   375

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

   376

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

   377

   378

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

   379

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

   380

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

   381

    """

   382

   383

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

   384

   385

    newConfig    = {}

   386

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

   387

    WebParamList = _WebNodeList[WebNode_id]["WebParamList"]

   388

   389

    for WebParamListEntry in WebParamList:

   390

        par_name = WebParamListEntry[0]

   391

        value = kwargs.get(par_name, None)

   392

        if value is not None:

   393

            newConfig[par_name] = value

   394

   395

    # First check if configuration is OK.

   396

    # Note that this is currently not really required for most of the parameters,

   397

    # as we use drop down choice menus for baud, parity and sop bits

   398

    # (so these values should always be correct!).

   399

    # The timing properties (period in ms, delays in ms, etc.)

   400

    # do however need to be validated as the web interface does not

   401

    # enforce any limits on the values (e.g., they must be positive values).

   402

    # NOTE: It would be confusing for the user if we simply refuse to make the

   403

    # requested changes without giving any feedback that the changes were not applied,

   404

    # and why they were refused (i.e. at the moment the web page does not have

   405

    # any pop-up windows or special messages for that).

   406

    # That is why instead of returning without making the changes in case of error,

   407

    # we instead opt to change the requested configuration to the closest valid values

   408

    # and apply that instead. The user gets feedback on the applied values as these get

   409

    # shown on the web interface.

   410

    #

   411

    # TODO: Check IP address, Port number, etc...

   412

    _CoerceConfigurationValues(WebNode_id, newConfig)

   413

   414

    # store to file the new configuration so that 

   415

    # we can recoup the configuration the next time the PLC

   416

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

   417

    _SetModbusSavedConfiguration(WebNode_id, newConfig)

   418

   419

    # Configure PLC with the current Modbus parameters

   420

    _SetModbusPLCConfiguration(WebNode_id, newConfig)

   421

   422

    # Update the viewable configuration

   423

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

   424

    # so we do not set it directly to newConfig

   425

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

   426

   427

   428

   429

def OnModbusButtonReset(**kwargs):

   430

    """

   431

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

   432

    The function will delete the file containing the persistent

   433

    Modbus configution. More specifically, reset to the configuration

   434

    hardcoded in the source code (<=> configuration specified

   435

    in Beremiz IDE).

   436

    """

   437

   438

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

   439

   440

    # Delete the file

   441

    _DelModbusSavedConfiguration(WebNode_id)

   442

   443

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

   444

    new_config = _WebNodeList[WebNode_id]["DefaultConfiguration"]

   445

    _SetModbusPLCConfiguration(WebNode_id, new_config)

   446

   447

    #Update the webviewconfiguration

   448

    _WebNodeList[WebNode_id]["WebviewConfiguration"] = new_config

   449

   450

    # Reset ModbusSavedConfiguration

   451

    _WebNodeList[WebNode_id]["ModbusSavedConfiguration"] = None

   452

   453

   454

   455

   456

   457

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

   458

    """

   459

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

   460

    the configuration parameters of a specific Modbus plugin node.

   461

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

   462

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

   463

    node versions of the Get/Set functions)

   464

    """

   465

    WebNode_entry = {}

   466

   467

    # Get the config_name from the C code...

   468

    config_name = GetParamFuncs["config_name"](C_node_id)

   469

    # Get the addr_type from the C code...

   470

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

   471

    addr_type   = GetParamFuncs["addr_type"  ](C_node_id)   

   472

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

   473

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

   474

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

   475

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

   476

   477

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

   478

   479

    # Add the new entry to the global list

   480

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

   481

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

   482

    global _WebNodeList

   483

    _WebNodeList.append(WebNode_entry)

   484

    WebNode_id = len(_WebNodeList) - 1

   485

   486

    # store all WebNode relevant data for future reference

   487

    #

   488

    # Note that "WebParamList" will reference one of:

   489

    #  - TCPclient_parameters, TCPserver_parameters, RTUclient_parameters, RTUslave_parameters

   490

    WebNode_entry["C_node_id"    ] = C_node_id

   491

    WebNode_entry["config_name"  ] = config_name 

   492

    WebNode_entry["config_hash"  ] = config_hash

   493

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

   494

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

   495

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

   496

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

   497

    WebNode_entry["GetParamFuncs"] = GetParamFuncs

   498

    WebNode_entry["SetParamFuncs"] = SetParamFuncs