Difference between revisions of "Smart Terminal Parameter Examples"

From OpenCircuits
Jump to navigation Jump to search
 
(58 intermediate revisions by the same user not shown)
Line 1: Line 1:
= What/Why the Parameter File =
+
= What/Why/How the Parameter File =
  
A lot of the behaviour of the terminal is controlled by the file '''parameters.py'''.  Different projects of mine require different parameters.  There are several way to achieve this.  The simplest to understand might be to have a different files for each projectYou can do this if you want, starting from my parameter file.  You can also use a secondary parameter file that overrides the settings in the first fileBut right now I am working with a somewhat different method that seems easier to manage.  This is the method in the supplied parameter file and the one that I will explain hereThe parameter file is heavily commented and these comments should be read if you have questions.  You can also search other files for parameters.xxx where xxx is the name of the parameter you are investigating.
+
A lot of the behavior of the terminal is controlled by the file '''parameters.py'''.  Different projects of mine require different parameters.  The first parameters that might spring to mind are the port and baud rate for the terminalBut the parameter file can change so much more: some are simple like adding a colored band to the terminal ( useful if you have more than one terminal running at a time ) to adding whole new modules that modify the graphical user interface ( GUI ) and add automatic processingWhile this file has the basic structure of a asci text file, you should keep in mind that it is an executable Python file.  This means it is programmatic, you can use any Python you want ( pretty much ) but try to limit yourself to setting the value of instance variables in the parameter object.
  
In the __init__ method after a couple of required lines that help hold the application there is a call to self.default_terminal_mode().  This subroutine sets a ton of parameters and this is enough to make the terminal run nicely.  See the comments in the subroutine for more info.
+
More information on this approach to configuration in: [[Configuration Files For Python]].
  
I then have a call to a short ( so far ) subroutine self.computer_name_tweaks(  )  This subroutine uses the already set parameter  computername to tweak a few settings depending on the computer's name. 
+
== Different Approaches ==
this makes it easy for me to change the default parameters setting based on the computer I am using to run the program.  Thus I can move the program around without changing the parameter file.
 
  
 +
*  To start with you can just run with the parameter file as shipped.  This gives a reasonable terminal that runs fine, but probably will not run with the baud rate and comm port that you desire, so almost for sure you will need to adjust these.  There are lines near the top of the parameter file to do this.  For more info see the section below.
  
The details of each parameter are commented in the parameter files, and you may also find it helpful to search the other SmartTerminal files to find their use.  If at any point you find it useful to add parameters that is ok as long as you do not use a name already in use.
+
* Another method is to use different parameter files for different projects.  These might be copied into the smart terminal directory when you want to use themWorks fine but is cumbersome.  Start from my file and modify. I do not recommend this approach, but you may want to do it.
  
A final twist in the use of the parameter file is that you can have a "second" parameter file that is run after the first.  This is specified in the command line in the form:  parameters=parameters_a  where parameters_a.py is another specifications of parameters.  This second file need not include all values, just changes after the main file runs.  It is particularly useful when running 2 instances of smart terminal and you may want different communications parameter and perhaps id colorIf used its use is noted in the title for the terminal.
+
* You can also use a secondary parameter file that overrides the settings in the first file.  This is great if you want to run 2 copies of the terminal.  Which secondary parameter file is used is controlled from the command line.  For more info see the section below. ( coming soon )
  
= Basic Parameter Example =
+
* The subroutine method.  This is what I recommend for most uses.  It is easy to manage and easy to switch between parameter sets.  This is the method in the supplied parameter file and the one that I will use for may discussion of how the parameter file works in general.  The parameter file is heavily commented and these comments should be read if you have questions.  You can also search other files for parameters.xxx where xxx is the name of the parameter you are investigating.
  
'''All this has been changed and simplified, write up coming.'''
+
== How to Edit the Parameter File ==
  
 +
Yous can use any editor you want ( for text type file ).  One warning, however, is not to use an editor that inserts tab characters, tabs are ok if they are converted to spaces but not otherwise.  Use your Python editor, that should be fine.  For an external editor I use notepad++ on windows but make sure you use the tab to spaces conversion option ( google it ).  The parameter file can be set up ( .ex_editor: for example self.ex_editor  =  r"leafpad" # linux editor ) so that a button <Edit Parms> on the GUI will open the parameter file in the editor.  After saving the file you can get a very fast restart of the app with the new parameter using the <Restart> button.
  
 +
= Structure of the Default Parameter File =
  
*This is based on the file ..../smart_terminal/example_parms/parameters_basic.py.
+
In the '''__init__''' method after a couple of required lines that help hold the application together there is a call to '''self.default_terminal_mode()'''.  This subroutine sets a ton of parameters
*The parameters are all that are needed for a basic terminal application, nothing fancy but all the basics, and much more than the arduino serial monitor.
+
and this is enough to make the terminal run nicely. See the comments in the subroutine for more info.
*Well commented read the file!
+
 
 +
I then have a call to a short ( so far ) subroutine called '''os_tweaks( )'''. This subroutine uses a parameter identifying the OS you are running on to tweak some of the settings.  These may be useful to you or not.  Change them if you want.
  
== What this Parameter File Does ==
+
In a similar way there is a subroutine called '''self.computer_name_tweaks(  )'''  This subroutine uses the already/automatically set parameter  '''computername''' to tweak a few settings depending on the computer's name. This makes it easy for me to change the default parameters setting based on the computer I am using to run the program.  Thus I can move the program around without changing the parameter file. These setting, as shipped, are probably not useful to you, but they may be useful as an example.
  
*Sets part of the title of the application.
+
Finally there is a list of calls to subroutines, typically each one is for a different type of setup or mode, all but one should be commented outSo I might make a call to a subroutine like:  '''self.well_monitor_mode()'''This is the mode for an arduino/python project that monitors my water well pressureIt is a pretty complicated set up, because of the database access in the well monitorFor this documentation I will do a subroutine called '''tutorial_example_mode()''' which make the most basic changes from the default mode.
*Sets the communications parametersSometimes a little confusing about port namesThe arduino IDE sometimes is better at finding the name, check itAlso use the <Ports> button on the GUIOn the apple we have found from <Ports> ('/dev/tty.usbmodem1411', True) and in the parameter file using '''self.port = "/dev/tty.usbmodem1411"''' gave a good connection.  Sometimes a reboot will result in a change of the port name.
 
*Specifies a program for file editing.
 
*Sets the size of the application.
 
*Defaults data to be sent.
 
*Change number of send areas.
 
*More see the file.
 
  
= An Intermediate Difficulty Parameter Example =
+
= Subroutine Method =
 +
All the rest of the documentation will refer to this method of structuring the parameter.py file.  You could instead just have a separate parameter file for each application/mode that just ran from top to bottom.  I have found this method more useful.
  
*This is based on the file ..../smart_terminal/example_parms/parameters_intermediate.py.
 
*The parameters include all the basic parameters plus ones to support a greenhouse arduino monitor.
 
*You should also look at the arduino application and the SmartTerminal extension to support it [[GreenHouse Monitor Program]] as they are closely related.
 
*Well commented read the file!
 
  
== What thisParameter File Does ==
+
== tutorial_example_mode() ==
  
*Everything the basic file does plus the following.
+
This mode just changes the default baudrate and the buttons/default data for the buttonRead the comments ( here or better in the actual file ) , they are pretty clear:
*The SmartTerminal needs some additional code to support the GreenHouse arduino programThe code is '''gh_csv_processing.GHCSVProcessing'''.  To cause this to be loaded we have the following:
 
  
 
<pre>
 
<pre>
         ....
+
 
         elif self.mode == "GreenHouseCSV":
+
    def tutorial_example_mode( self, ):
            # this is the module and class name of another class that will be built to support
+
        """
            # automatic processing of a anduino monitoring a greenhouse
+
        this mode does not do anything usefull except illustrate a simple "mode subroutine"
            # this also adds buttons to the gui
+
         """
            self.ext_processing_module      = "gh_csv_processing"
+
         self.mode             = "TutorialExample" # this name will appear in the title of the window
            self.ext_processing_class       = "GHCSVProcessing"
+
                                                    # to help keep track of which mode you are using
 +
 
 +
        self.baudrate          = 19200              # changes the baucrate from the default to 19200
 +
 
 +
        # the send_ctrls is a list of 3 valued tuples
 +
        # for each item in the list you will have a "send button", a button that will send the contents of
 +
        # the data entry field to the right of it to your comm port.
 +
        # the first item of the tuple is a sting whose test will be on the button
 +
        # the second is a string with the initial or default value for the data entry field
 +
        # the third is a boolean, True make the data entry field editable, otherwise it is protected from edit
 +
        self.send_ctrls = [
 +
                # text                      cmd              can edit
 +
                ( "Send",                    "",              True ),
 +
                ( "Send",                    "",              True ),
 +
                ( "Different Title",        "default",       True ),
 +
                ( "More Different",          "yes different", True ),
 +
                ]
 +
        # you may get extra buttons with default values to fill the space
  
 
</pre>
 
</pre>
  
In the code above we use the "meta" parameter self.mode to make it easy to switch on/off these settings ( by changing self.mode ).
+
= Another example mode =
 +
 
 +
make it a bit more complicated.  Still needs to be written.
 +
 
 +
= Reference/Summary for Some Values =
 +
 
 +
Instance variables and their meanings ( in code use self.xxxx as they are instance variables ).  This reference is not detailed/exhaustive, for that you must use the supplied parameters.py and its comments.
 +
 
 +
== Overview ==
 +
 
 +
* '''logger_id''':  the id used in the logging file
 +
* '''pylogging_fn''': file name for the python logging
 +
* '''logging_level''':  python logging level of severity for message to be logged to the logging file     
 +
* '''win_geometry''':  the size of the window when first opened
 +
* '''ex_editor''':  name of an executable file used to edit files related to the terminal 
 +
 
 +
== Comm Related ==
 +
 
 +
* '''port_list''':  a list of ports that the automatic connect routine will use to find a connection
 +
* '''port''':  default port to open 
 +
* '''baudrate''': comm port baudrate
 +
     
 +
* '''serialAppend''':  characters ( like cr and lf ) placed at the end of transmitted strings 
 +
* '''auto_open'''        = False      # true to open port on start up  #  !! *todo
 +
 
 +
* '''prefix_send''':  a prefix shown in the "receive area" to show that the data has been sent
 +
* '''prefix_rec''':  a prefix shown in the "receive area" to show that the data has been recieved
 +
* '''prefix_info''':  a prefix shown in the "receive area" prefix for informational messages
 +
 
 +
* '''echoSend''':  locally echo the sent characters     
 +
 
 +
* '''get_arduino_version''': string sent to get arduino to respond with its version string
 +
* '''arduino_version'''        = "GreenHouse"    # should be part of the string th
 +
 
 +
* '''arduino_connect_delay'''      = 10    # may not be implemented yet
 +
 
 +
* '''gui_sends'''        = 15        # number of send frames in the gui beware if 0
 +
 
 +
* '''max_send_rows'''    = 3        # the send areas are added in columns this many rows long, then a new
 +
* '''default_scroll'''    = 1        # 1 auto scroll the receive area, else 0
 +
 
 +
== Extended Processing ==
 +
 
 +
If you want to add some of your own GUI and processing elements to the terminal the next parameters add a module name and class name that will be loaded into the application
 +
 
 +
*'''ext_processing_module''':  module name     
 +
*'''ext_processing_class''':  class name
 +
 
 +
== Automatically Set ==
 +
 
 +
*'''our_os''': "win32" if your are running windows -- used by os_tweaks().
 +
*'''computername'''  the name of your computer if available ( it is on windows, linux ?? ) used by computer_name_tweaks().
 +
 
 +
== For the Second Thread, the Helper Thread ==
 +
 
 +
* '''queue_length'''        = 20
 +
* '''queue_sleep'''          = .1
 +
 
 +
<!-----------
 +
this cannot bee seen
 +
 
 +
 
 +
 
 +
 
 +
# ----------  self.start_helper_function    = gh_processing.GHProcessing.find_and_monitor_arduino
 +
start_helper_function    = "find_and_monitor_arduino"    # now using eval, may need to do same with args,
 +
start_helper_args        = ( )    # () empty  ( "x", ) one element
 +
start_helper_delay      = 0      # in seconds  must be > 0 to start
 +
 
 +
# This is how often in ms to poll the comm port, faster makes it more responsive, uses
 +
# more resources
 +
* '''gt_delta_t'''        = 50              # in ms --  lowest I have tried is 10 ms, could not see cpu load
 +
 
 +
* '''ht_delta_t'''        = 100/1000.        # TIME FOR helper thread polling this uses time so in seconds, sorry for confusion
 +
 
 +
self.send_array_mod    = 5                # see task, send array
 +
 
 +
# ?? not implemented should it be?
 +
block_port_closed = False            # block sending if port is closed  # *todo  -- or some warning
 +
 
 +
 
 +
------------->
 +
 
 +
== Appearance ==
 +
 
 +
* '''id_color''': color for an "ID pane" just below the title bar of the window
 +
* '''id_height''': height of the "ID pane" if 0 there is no pane
 +
* '''bk_color'''          = "blue"  # color for the background, you can match the id color or use a neutral color like gray
 +
* '''icon''':  name of icon for the application
 +
* '''mode''' name for the mode of the SmartTerminal, used in the title of the SmartTerminal window and may be use in code.
 +
* '''self.win_geometry''' a string that specifies the initial size of the SmartTerminal window
 +
 +
<!-----------
 +
 
 +
 
 +
 
 +
Sets the communications parameters. Sometimes a little confusing about port names. The arduino IDE sometimes is better at finding the name, check it. Also use the <Ports> button on the GUI. On the apple we have found from <Ports> ('/dev/tty.usbmodem1411', True) and in the parameter file using self.port = "/dev/tty.usbmodem1411" gave a good connection. Sometimes a reboot will result in a change of the port name.
 +
Specifies a program for file editing.
 +
 +
Defaults data to be sent.
 +
Change number of send areas.
 +
this cannot bee seen
 +
 
 +
 +
== More on Particular Parameters ==
 +
 
 +
=== Parm 1 ===
 +
=== Parm 2 ===
 +
this cannot bee seen
 +
------------->
 +
 
 +
= Using a Second Parameter File  =
 +
 
 +
If you running 2 instances of the SmartTerminal you probably do not want to run with the same parameters ( they would use the same comm port ).  So if they run with different parameter files they can be quite different.  The idea here is they start with the same parameter file, parameters.py and are then extended with a second file ( say parameters_a.py or any other name you wish ).  This is done by using a command line.  For example:  '''python smart_terminal.py    parameters=paramaters_a'''
 +
 
 +
 
 +
The difference in this file is the parameters are not self.xx but parameters.xx.  Else it is pretty much the same.  See the example file parameters_a.py.
 +
 
 +
<!-----------
 +
this cannot bee seen
 +
 
 +
 
 +
 
 +
= delete soon =
 +
 
 +
 
 +
*You should also look at the arduino application and the SmartTerminal extension to support it [[GreenHouse Monitor Program]] as they are closely related.
 +
*Well commented read the file!
 +
 
 +
== What thisParameter File Does ==
 +
 
  
*The parameter file can be used to customize the send buttons, for the GreenHouse adaptation I use a more advanced version of these settings:
 
 
<pre>
 
<pre>
 
     self.send_ctrls        = [ ( "Version", "v", False ),  ( "Help", "h", False ), "simple default text" ]
 
     self.send_ctrls        = [ ( "Version", "v", False ),  ( "Help", "h", False ), "simple default text" ]
Line 67: Line 206:
 
*The terminal can probe the communications ports, find a port that opens, send a string to the arduino, and look for a particular response to verify that it is connected to the desired port.  This takes the following settings:
 
*The terminal can probe the communications ports, find a port that opens, send a string to the arduino, and look for a particular response to verify that it is connected to the desired port.  This takes the following settings:
  
<pre>
 
        self.get_arduino_version    = "v"              # sent out port to get arduino version
 
        self.arduino_version        = "GreenHouse"    # should be part of the string the arduino responds with match with the arduino code
 
</pre>
 
  
  
 
*Another setting is required for the probe of communications ports.  Here it is ( set up for automatic switching between operating systems )
 
*Another setting is required for the probe of communications ports.  Here it is ( set up for automatic switching between operating systems )
  
<pre>
 
 
        # used to probe around for ports
 
        if  self.os_win:
 
            self.port_list  =  [ "COM11", "COM12", "COM13", "COM14", "COM15", "COM16", "COM17", ]
 
        else:
 
            self.port_list  =  [ "/dev/ttyUSB0", "/dev/ttyUSB1", "/dev/ttyUSB2", "/dev/ttyACM0", "/dev/ttyACM1", "/dev/ttyACM2", ]
 
  
</pre>
 
  
 
* Data is saved to a csv file, but what is the file name.  Here is its setting:
 
* Data is saved to a csv file, but what is the file name.  Here is its setting:
Line 91: Line 218:
 
</pre>
 
</pre>
  
= even more =
+
------------->
  
  
[[Category:SmartTerminal]] [[Category:Arduino/RaspberryPi]]
+
[[Category:SmartTerminal]] [[Category:Arduino/RaspberryPi]] [[Category:Python]]

Latest revision as of 07:21, 24 October 2019

What/Why/How the Parameter File[edit]

A lot of the behavior of the terminal is controlled by the file parameters.py. Different projects of mine require different parameters. The first parameters that might spring to mind are the port and baud rate for the terminal. But the parameter file can change so much more: some are simple like adding a colored band to the terminal ( useful if you have more than one terminal running at a time ) to adding whole new modules that modify the graphical user interface ( GUI ) and add automatic processing. While this file has the basic structure of a asci text file, you should keep in mind that it is an executable Python file. This means it is programmatic, you can use any Python you want ( pretty much ) but try to limit yourself to setting the value of instance variables in the parameter object.

More information on this approach to configuration in: Configuration Files For Python.

Different Approaches[edit]

  • To start with you can just run with the parameter file as shipped. This gives a reasonable terminal that runs fine, but probably will not run with the baud rate and comm port that you desire, so almost for sure you will need to adjust these. There are lines near the top of the parameter file to do this. For more info see the section below.
  • Another method is to use different parameter files for different projects. These might be copied into the smart terminal directory when you want to use them. Works fine but is cumbersome. Start from my file and modify. I do not recommend this approach, but you may want to do it.
  • You can also use a secondary parameter file that overrides the settings in the first file. This is great if you want to run 2 copies of the terminal. Which secondary parameter file is used is controlled from the command line. For more info see the section below. ( coming soon )
  • The subroutine method. This is what I recommend for most uses. It is easy to manage and easy to switch between parameter sets. This is the method in the supplied parameter file and the one that I will use for may discussion of how the parameter file works in general. The parameter file is heavily commented and these comments should be read if you have questions. You can also search other files for parameters.xxx where xxx is the name of the parameter you are investigating.

How to Edit the Parameter File[edit]

Yous can use any editor you want ( for text type file ). One warning, however, is not to use an editor that inserts tab characters, tabs are ok if they are converted to spaces but not otherwise. Use your Python editor, that should be fine. For an external editor I use notepad++ on windows but make sure you use the tab to spaces conversion option ( google it ). The parameter file can be set up ( .ex_editor: for example self.ex_editor = r"leafpad" # linux editor ) so that a button <Edit Parms> on the GUI will open the parameter file in the editor. After saving the file you can get a very fast restart of the app with the new parameter using the <Restart> button.

Structure of the Default Parameter File[edit]

In the __init__ method after a couple of required lines that help hold the application together there is a call to self.default_terminal_mode(). This subroutine sets a ton of parameters and this is enough to make the terminal run nicely. See the comments in the subroutine for more info.

I then have a call to a short ( so far ) subroutine called os_tweaks( ). This subroutine uses a parameter identifying the OS you are running on to tweak some of the settings. These may be useful to you or not. Change them if you want.

In a similar way there is a subroutine called self.computer_name_tweaks( ) This subroutine uses the already/automatically set parameter computername to tweak a few settings depending on the computer's name. This makes it easy for me to change the default parameters setting based on the computer I am using to run the program. Thus I can move the program around without changing the parameter file. These setting, as shipped, are probably not useful to you, but they may be useful as an example.

Finally there is a list of calls to subroutines, typically each one is for a different type of setup or mode, all but one should be commented out. So I might make a call to a subroutine like: self.well_monitor_mode(). This is the mode for an arduino/python project that monitors my water well pressure. It is a pretty complicated set up, because of the database access in the well monitor. For this documentation I will do a subroutine called tutorial_example_mode() which make the most basic changes from the default mode.

Subroutine Method[edit]

All the rest of the documentation will refer to this method of structuring the parameter.py file. You could instead just have a separate parameter file for each application/mode that just ran from top to bottom. I have found this method more useful.


tutorial_example_mode()[edit]

This mode just changes the default baudrate and the buttons/default data for the button. Read the comments ( here or better in the actual file ) , they are pretty clear:


    def tutorial_example_mode( self, ):
        """
        this mode does not do anything usefull except illustrate a simple "mode subroutine"
        """
        self.mode              = "TutorialExample"  # this name will appear in the title of the window
                                                    # to help keep track of which mode you are using

        self.baudrate          = 19200              # changes the baucrate from the default to 19200

        # the send_ctrls is a list of 3 valued tuples
        # for each item in the list you will have a "send button", a button that will send the contents of
        # the data entry field to the right of it to your comm port.
        # the first item of the tuple is a sting whose test will be on the button
        # the second is a string with the initial or default value for the data entry field 
        # the third is a boolean, True make the data entry field editable, otherwise it is protected from edit
        self.send_ctrls = [
                # text                      cmd               can edit
                ( "Send",                    "",              True ),
                ( "Send",                    "",              True ),
                ( "Different Title",         "default",       True ),
                ( "More Different",          "yes different", True ),
                ]
        # you may get extra buttons with default values to fill the space

Another example mode[edit]

make it a bit more complicated. Still needs to be written.

Reference/Summary for Some Values[edit]

Instance variables and their meanings ( in code use self.xxxx as they are instance variables ). This reference is not detailed/exhaustive, for that you must use the supplied parameters.py and its comments.

Overview[edit]

  • logger_id: the id used in the logging file
  • pylogging_fn: file name for the python logging
  • logging_level: python logging level of severity for message to be logged to the logging file
  • win_geometry: the size of the window when first opened
  • ex_editor: name of an executable file used to edit files related to the terminal

Comm Related[edit]

  • port_list: a list of ports that the automatic connect routine will use to find a connection
  • port: default port to open
  • baudrate: comm port baudrate
  • serialAppend: characters ( like cr and lf ) placed at the end of transmitted strings
  • auto_open = False # true to open port on start up # !! *todo
  • prefix_send: a prefix shown in the "receive area" to show that the data has been sent
  • prefix_rec: a prefix shown in the "receive area" to show that the data has been recieved
  • prefix_info: a prefix shown in the "receive area" prefix for informational messages
  • echoSend: locally echo the sent characters
  • get_arduino_version: string sent to get arduino to respond with its version string
  • arduino_version = "GreenHouse" # should be part of the string th
  • arduino_connect_delay = 10 # may not be implemented yet
  • gui_sends = 15 # number of send frames in the gui beware if 0
  • max_send_rows = 3 # the send areas are added in columns this many rows long, then a new
  • default_scroll = 1 # 1 auto scroll the receive area, else 0

Extended Processing[edit]

If you want to add some of your own GUI and processing elements to the terminal the next parameters add a module name and class name that will be loaded into the application

  • ext_processing_module: module name
  • ext_processing_class: class name

Automatically Set[edit]

  • our_os: "win32" if your are running windows -- used by os_tweaks().
  • computername the name of your computer if available ( it is on windows, linux ?? ) used by computer_name_tweaks().

For the Second Thread, the Helper Thread[edit]

  • queue_length = 20
  • queue_sleep = .1


Appearance[edit]

  • id_color: color for an "ID pane" just below the title bar of the window
  • id_height: height of the "ID pane" if 0 there is no pane
  • bk_color = "blue" # color for the background, you can match the id color or use a neutral color like gray
  • icon: name of icon for the application
  • mode name for the mode of the SmartTerminal, used in the title of the SmartTerminal window and may be use in code.
  • self.win_geometry a string that specifies the initial size of the SmartTerminal window


Using a Second Parameter File[edit]

If you running 2 instances of the SmartTerminal you probably do not want to run with the same parameters ( they would use the same comm port ). So if they run with different parameter files they can be quite different. The idea here is they start with the same parameter file, parameters.py and are then extended with a second file ( say parameters_a.py or any other name you wish ). This is done by using a command line. For example: python smart_terminal.py parameters=paramaters_a


The difference in this file is the parameters are not self.xx but parameters.xx. Else it is pretty much the same. See the example file parameters_a.py.