Release 3.8

docs/currentchanges.txt

@@ -74,3 +74,8 @@ This release primarily adds support for soft rotation of the display that is req
 The console install scripts have been streamlined in this release to avoid the second reboot that used to be required.  This should somewhat speed up installation although the bulk of the time is still in updating the base system to current.
 
  The release also fixes a bug when an alert screen gets invoked while in Maintenance mode, a bug in MQTT status handling.  It also reworks Home Assistant restart code to insure that states are correct for changes that happened while the console was offline.  Finally it again adjusts the use of Adafruit install script use to handle their changes related to a 28c PiTFT.
+
+V3.8
+This release adds a new screen type "Picture" to the console that allows the console to also act like a photo frame.  It supports a directory mode that sequentially displays jpg files found in that directory to the screen while that screen is active.  The directory is monitored for changes and those are reflected in the displayed photos within a few cycles.  It also supports a single picture mode that displays only a single jpg which is monitored for changes.  In this mode changes are reflected to the display within 3-4 seconds and so is suitable for use if the desire is to display changing screen captures or the like.  See the description in the useage notes for all the details on how it works.
+
+The release also adds support for username/password for MQTT which was previously missing.  It adds an advanced network node command to the maintenance screens to clear retained knowlege of a dead node from the MQTT broker.  It also will handle MQTT server down situations more gracefully.  Finally, it adds a small developer oriented feature to enable personalized operations to be done on every console boot.  See the Developers Notes section of the useage notes for more information.

docs/useagenotes.md

@@ -266,6 +266,8 @@ Note that all the elements referring to keys may be explicitly specified at the
 If you set a non empty title for a screen that doesn't otherwise have one, the rest of the screen shrinks vertically to allow the space.  If ScreenTitleFields lists store items then these are substituted into the title whenever the screen is rendered (including when it is rendered based on "Clocked").  Substitution is based on standard Python formatting rules as defined in https://docs.python.org/3.7/library/string.html.  
 
 ## Screen Types
+
+### Keypad
 * Keypad: mimics the KPL.  Can support any number of buttons from 1 to 25 and will autoplace/autosize buttons in this range.  Parmetrs KeysPerColumn and KeysPerRow may be used to override the auto placement of the keys.  Keys may be colored as desired.  Key types are:
     * ONOFF: linked to a device or scene and supports On, Off, FastOn, FastOff behaviors
     * RUNPROG: linked to a program to run.  It issues a RunThen on the designated program for ISY hubs. It issues a automation.trigger for the automation for HA hubs.
@@ -294,10 +296,15 @@ If you set a non empty title for a screen that doesn't otherwise have one, the r
         * FastPress = 1: requires a quick double tap to activate the key. (Note not applicable to the ONOFF keys since there a double press corresponds to issuing a fast on or off to the device).
 
     * Note: for scenes ONOFF will choose a device to use as a proxy for the state of the scene for purposes of the appearance of the button.  Generally this will turn out to be some other switch or KPL button that is a controller for the scene.  This can be overridden by supplying a specific device address or name to use as the proxy.
+
+### Clock
 * Clock: displays a clock formatted according to the OutFormat parameter using any of the underlying OS time formatting codes.  The character size for each line can be set individually.  If there are more lines in the format than character sizes the last size is repeated. Python standard formatting is at https://docs.python.org/2/library/time.html.  Linux (RPi) supports a somewhat richer set of codes e.g. http://linux.die.net/man/3/strftime
-* Weather: uses a weather provider to display current conditions and forecast.  The location parameter is a location code defined as above.    
+### Weather
+* Weather: uses a weather provider to display current conditions and forecast.  The location parameter is a location code defined as above.
+### Thermostat    
 * Thermostat: mimics the front panel of the typical thermostat and provides full function equivalency.  Has been tested with Insteon thermostat via ISY and Nest Thermostat via HA but should work with any device those hubs support.
 This screen uses an improved update approach for the setpoints.  Touching the setpoint buttons only adjusts the values locally on the console and greys the values to indicate this.  If no additional touch is seen for 2 seconds then the resultant setpoint is pushed to HA and thus the thermostat.  The displayed values remain greyed until an update from the thermostat indicates it has set them or an addition time period passes after which the actual current setpoints are retrieved and displayed normally.  Thus if an error occurs updating the setpoints on the actual thermostat you may see the old setpoint reappear indicating something went wrong.  This makes changing setpoints not have to wait for the latency to the hub and back for each degree of change.
+### Time/Temp
 * Time/Temp: combined screen, nice as a sleep screen that gives current time and the weather.  Format of the screen is largely controlled by the config.txt file.  The location is displayed unless you set the character size for that line to 0.  An icon can be displayed as part of the current conditions by setting CondIcon = True.  An icon canbe displayed as part of each forecast day by setting FcstIcon = True.  There are a variety of options for the display of the forecast days that can be selected by setting FcstLayout in the config file.  They are:
     * Block: forecast items are left aligned in a block that is centered based on the longest item (1 column) 
     * BlockCentered: forecast items are individually centered but multiline items are left aligned (1 column)
@@ -308,8 +315,14 @@ This screen uses an improved update approach for the setpoints.  Touching the se
     Fields that are referenced in the format descriptions of the config file will use the store corresponding to the location code specified for the screen and the type of field group being specified by default.  E.g., if the location is specified as KPDX then the default for a field, \<field\>, mentioned in the ConditionFields is KPDX:Cond:<field>.  However, any field in any part of the screen can be explicitly notated.  E.g., in the ConditionFields one could specify FOO:Fcst:High:1 to reference the forecast field for the next day high at FOO or MQTT:Humidity to reference some field Humidity that is supplied via an MQTT broker named MQTT.
 
     There are four regions of the screen each with its own character sizing parameter.  The font size of the clock area is given as **ClockSize**, that of the location as **LocationSize** (where 0 suppresses the location line), the current conditions block as **CondSize**, and the forecast block as **FcstSize**.  Note that for the current conditions and forecast blocks which can be multiline the appropriate size parameter can be a list of sizes which then apply sequentially to the lines.  The old parameter **CharSize** is deprecated.  It works currently but will be removed in the future.
+### Picture
+The Picture screen (type=Picture) is used to allow the console to function as a photo frame if desired.  It can function in one of 2 modes: directory mode and single mode.
 
-    * Alert: used to display an alarm condition - see below.
+In its default mode (directory) it will rotate through pictures (which must be jpg files) in a given directory.  The directory is designated by the parameter picturedir.  If no picturedir parameter is provided the directory pics in the config directory (normally Console) is used.  If a picturedir parameter is provided, if it starts with a "/" it is used as an absolute path to the picture directory.  If it does not start with a "/" then it is interpretted as a path starting with the config directory.  A parameter picturetime sets the hold time in seconds for each photo on the screen and defaults to 5 seconds.  Pictures are oriented on the screen based on orientation information in the jpg exif if that exists, so for most digital photos they will display correctly automatically. In operation the picture screen remembers where in the photo it is so that if used as one screen in a set of idle screens it will pick up displaying photos where it left off when it was last active.  The directory is monitored for changes and the stream of photos will dynamically reflect those changes.  Since there is some pipelining involved, the changed photos may take 2-3 multiples of picturetime to be visible.  Also of note, the pictures are cached by the console, locally in a process format to improve efficiency.  If the source of the directory is a network drive this means that the photos will only use network bandwidth when they are first being displayed which, given the size of typcial modern jpgs is a significant efficiency.
+
+To use the screen in single mode provide a parameter "singlepic" which provides an absolute path to a jpg file (if it starts with "/") or a path relative to the config directory to a jpg file.  Parameter picturetime is not used in this mode.  The designated file is monitored for changes every second and will be reloaded if it changes.  Thus for single mode the screen will reflect changes typically within a few seconds of making the change.  This is helpful if the jpg is actually a screen shot that is being updated or some other such dynamic information.  Since the file is only reloaded when it changes no caching is done for single mode.
+### Alert
+* Alert: used to display an alarm condition - see below.
 
 # Alerts
 Alerts are defined in an "\[Alerts\]" section of the config files.  See cfglib/pdxalerts for some examples.  Currently alerts can be triggered periodically, based on a node state chance, or based on a variable state change.  The effect of the alert can be delayed by some time to avoid alerts for routine events that should clear within some typical window.  Alerts can either invoke an alert screen (see the away and garage alerts in the sample file) or an alert procedure (see the update alert).
@@ -351,6 +364,9 @@ Tapping on the screen 5 time puts the console in maintenance mode and changes to
 If the console is connected to an MQTT broker then an additional capability will appear for Network concoles.  From here you can display the current status of all consoles on your network, their hardware/OS and console versions, and issue commands to them.  If you choose to issue commands you will get a screen that lets you choose the console to interact with.  Selecting a console will let you see its log (or a reverse ordered recent list of errors it has encountered from that log), command it to download versions, restart, reboot, etc.  Note that double tapping on the node name accesses some advanced commands meant mostly for debugging.
 
 # Developers Notes
+## Local Operations
+During console start up it will attempt at a very early stage (before the config file has been chosen or opened) to execute a Python procedure localops.PreOp().  The localops module will be one found in the parent directory of the direcory holding the source code.  E.g., if running the code from /home/pi/consolestable it will look first for a file localops.py in /home/pi and then for a file localops.py in the source directory.  This allows you to write a Python script that performs something you need done on every console start.  The console will also call localops.LogUp() once the console log has been initalized.  This premits the PreOp procedure to arrange to have information logged once the log is started.  There is an example of my personal localops module in the sources that can be used for ideas if you need this capability.  Note that this version checks for "homesystem" so should be a noop on most systems.
+
 ## Defining New Screens by Coding a Module (updated for version 2)
 New screens can be developed/deployed by subclassing screen.ScreenDesc and placing the code in the screens directory.  Screens modules have a single line of code at the module level of the form "config.screentypes[*name*] = *classname*" where *name* is the string to be used in config files to as the type value to create instances and *classname* is the name of the class defined in the module.  A screen class defines the following methods (ScreenDesc provide base level implementations that should be called if overridden):
 

example configs/config-rpi-dev7.txt

@@ -22,7 +22,7 @@ DimIdleListNames = MyClock, Pic, PDXTTbig, LQTTbig, LQTTbigdks, Pumpkin
 
 DimIdleListTimes =	5, 20, 5, 5
 
-MainChain = Prusa, wxHouse,TreeTest, LR1,Sonos,LR2, Pumpkin, Local, Upper Level, Test #Creator Pro,
+MainChain = Prusa, wxHouse, Pic, TreeTest, LR1,Sonos,LR2, Pumpkin, Local, Upper Level, Test #Creator Pro,
 SecondaryChain = Portland, Bathroom, BR, Thermostat - Main,LQTTbig, climate.master_bedroom, climate.living_room, pgawBR, pgawOther, pgawBath
 
 DefaultHub = ISY
@@ -65,7 +65,7 @@ CharColor = white
 
 [Pic]
 type = Picture
-#singlepic = '/home/pi/Console/spcpic.jpg'
+#singlepic = 'spcpic.jpg'
 
 [Alerts]
 	[[AutoVersion]]