5,838
edits
MX Basic info: Difference between revisions
m
Resequence, with some updating
m (change to standard banner) |
m (Resequence, with some updating) |
||
|
This page contains some reference information about MX, that applies whatever operating system you run MX on.
It was correct at release 3.5.0, some updates have been made for later releases, but more work is needed.
{{Template:WorkInProgressBanner}}{{Template:Version badge Mx}}
= The provided web pages =
<big>THIS SECTION APPLIES FOR MX 3.0.0 TO 3.9.7 ONLY</big>
Setting up a web site was long, long ago,covered in [[Website_setup|this wiki page]] and the pages linked from there. I won't repeat that, but will try to explain below the MX context of the various files involved in the beta MX by Steve Loft.
MX will produce web pages locally even if you don't have a remote web site to display them on. You can view the web pages created in the web folder using a browser.
Cumulus MX (MX 3.0.0 TO 3.9.7 ONLY) provided a set of web templates, images, and json files, in '''\CumulusMX\web'''.
#The first of these are called templates (and have a 'T' at the end of the file name before the extension) because they include both text and web tags.
#MX will '''process''' these templates as it creates a web page (file name without a "T" in same web folder), during that processing, any text in the template is copied into new file without change, any web tags found in the template are parsed and the correct value is placed in that position in the output file.
#If you have a web server, then MX can process these files and upload them for you (by default using File Transfer Process) providing you specify the host, port, protocol, directory, username, and password, for the upload process to use. If you don't understand any of these terms, then this is not the place for explaining them, but generally if your web space is supplied by a provider, they will be able to tell you most of these settings, and you will choose the directory name. If you have set up a web server yourself, then you should know the required settings.
The web templates included (MX 3.0.0 TO 3.9.7 ONLY) were based on designs by Beth Loft used for Cumulus 1, with minimal modifications (apart from trendsT.htm and gaugesT.htm which were new designs). Remember, Steve Loft (who wrote the original Cumulus software) said "''They exist because they're our web pages, and they're really only included with Cumulus as examples of how the web tags work. It never occurred to me that most people would simply use the supplied examples instead of creating their own pages!''"
The templates (MX 3.0.0 TO 3.9.7 ONLY) were written in fairly simple Hyper-Text Mark-up Language, designed to help people see how to write their own web templates. Here is a list of web templates provided:
*indexT .htm
*todayT.htm
*yesterdayT.htm
*thismonth.htm
*thisyear.htm
*recordT.htm
*monthlyrecordt.htm
*gaugesT.htm
*trendsT.htm
All these templates (except gaugesT.htm and trendsT.htm) included a table for showing values and styling that gave a graded background colour. The tables included a navigation row with links to the other pages in the set. '''That navigation line fixes the width of the table''', and you will realise it was designed in the days when all monitors were a standard shape. Therefore the standard web pages as provided cannot adapt to the range of devices we use for viewing web pages nowadays. There are a selection of alternative web page sets available [[:Category:User_Contributions#web_template_complete_set_replacements|on the User_Contributions page]], and some of these are responsive and adapt to the width of the device they are being viewed on.
The gaugesT.htm is a template similar to [[SteelSeries Gauges]] although the latter is designed to work with a range of software and the former is specific to MX. '''As supplied in MX if you mouse over the provided gauges appearing on your web site you will see a box with figures, not a graph as is seen with the general steel series gauges''', but there are some other differences such as how the figures are supplied for the displays. The remaining template '''trendsT.htm''', creates a structure that can display graphs. The data for all the graphs that can be displayed is contained in the various '''json''' files in '''\CumulusMX\web''', these files are also processed by Cumulus so latest values are added, and then uploaded so the web page produced by this template can use them.
The image that is provided in '''\CumulusMX\web''' is ''MoonBaseImage.png'', MX can be set to use that to generate (on MX start-up and on the hour) "moon.png" which it then can FTP to your web (also on the hour).
== To set up your web server for the first time ==
When you first want to use Cumulus web pages on your web server, you need a number of static (unchanging) files to be put onto your web server. The web pages that MX uploads for you reference that static files and will not look right without them. The files that only have to be uploaded once are found in '''\CumulusMX\webfiles''' and its sub-folders. You don't create a folder called webfiles on your web server, but you put the files and sub-folders into position relative to where MX will upload the htm files.
To do this, you will must invoke a FTP process outside of Cumulus, MX does not include any functionality to do this one-off upload for you. The filezilla client is a popular choice as it has probably the most friendly graphical user interface, although other software to do this is also available. You may prefer a tool that lets you do the uploads from a command line without requiring working with a graphical interface.
#The static files to be uploaded include the standard styling file '''\CumulusMX\webfiles\weatherstyle.css''' which you place in the directory specified for the uploads.
#Next you have three sub-folders, each of those sub-folders need to be replicated '''within''' the directory specified for the uploads.
#*For example '''\CumulusMX\webfiles\images\picture.jpg''' will be stored in a "images" sub-directory of the upload directory and is used as the background image for web pages.
#**There is nothing to stop you creating your own "picture.jpg" (instead of uploading the supplied one) and then Cumulus web pages will use that for the background image on each page.
#*Similarly '''\CumulusMX\webfiles\js\cumuluscharts.js''' needs to be stored in a "js" sub-directory of your upload directory (this is the script that allows you to change the chart shown on the trends page and uses the appropriate json file to populate it with data).
# The "lib" sub-folder contains further levels of sub-folders all to be replicated on your web site.
# The '''trends.htm''' web page also loads some library software from an internet Content Delivery Network (cdn) to invoke the JavaScript based Highstocks library.
== Operating a web site with uploads from MX engine ==
=== The standard web pages ===
*If you want to operate the 'standard' web site, then just the same as with Cumulus 1, you will need to upload the ''contents'' of the '''webfiles''' folder from the zip file (don't upload the containing '''webfiles''' folder itself).
**Note that the MX web files are not the same as the ones for Cumulus 1, so make sure you upload the MX files if moving from Cumulus 1 to MX.
**The standard gauges are now the SteelSeries gauges. The default versions do not display a graph when you hover over a gauge as happened when you added the stand-alone Steel Series gauges to Cumulus 1.
**The trends web page in Cumulus 1 relied on that software generating graphs as images. In MX, the software generates files with time and value pairs, these are stored in json format, the trends page then uses a library package (Highstocks) to draw graphs from those data pairs.
=== Alternative ways to obtain web pages ===
You can choose to use some of the alternative web pages available from third parties and described [[:Category:User Contributions|on User Contributions page]].
=== Using your own web pages ===
*Of course you can use your own web pages, instead of the standard ones. Assuming they need to include figures that are available as web tags, there are three alternative ways to implement this:
*#MX can process template files with a HTML structure and those web tags in the structure where values are required just as it does with the standard templates, and MX can upload the resulting web pages at either the real-time interval, the standard interval, or after end of day. All of this is covered on the [[Customised_templates|Customised templates]] page in this Wiki.
*#MX can process a file with a string of web tags mirroring the realtime.txt option in MX, and upload the resulting file so your web pages can use JavaScript for a one-off insert of the values or an Ajax routine to update the web page at a fixed interval.
*# Alternatively, you can use template scripts processed locally by MX that don't create web pages, but are uploaded by MX at either the real-time interval, the standard interval, or after end of day. These scripts simply initialise script variables with values obtained from web tags. You then independently have a set of web pages resident only on your web server (they don't exist where you run MX) using a combination of HTML and script content that bring in the script(s) with the variables by the appropriate syntax. All of this is covered on the [[Php_webtags|PHP web tags]] page in this wiki. As it suggests there, you might therefore have several files processed by Cumulus MX at these different intervals, converting the web tags into script variables, and then use AJAX (JavaScript that may use json format to bring in the variables) or PHP (using <tt>'require_once 'filename';</tt> syntax) to put those variables into a web page.
You may find [[PHP|this wiki page]] useful for understanding more about the different script languages.
= MX End of Day Process =
I have added this section, because this process has given me some headaches.
== My version ==
If you write custom SQL, or have a template being processed at end of day, then what I find strange is that web tags related to system date report the new date, but other web tags report weather derivatives from the old day. Put another way, all the date related tags change at start of rollover, but all the weather related web tags change at end of rollover.
However, it is not quite as simple as that, the month and year are reset before the extra web files are processed (so they cannot use monthly web tags at end of month, nor yearly web tags at end of year). The complication is that in the extra web files you can use '''<currentlogfile>''' (and from build 3087 '''<currentextralogfile>''') and these pick up the old month/year. Now you see why I found it hard to digest, and why I wanted to write it here to make it easier for others.
If you use Custom SQL and therefore have to quote web tags, the SQL should use monthly and yearly web tags related to previous day, but all the weather tags it uses must be those for current conditions or today. Yes it is confusing.
As part of the so called "end of day" process, MX (just like Cumulus 1) creates a start of day back up in the daily sub-folder. So on first day of a new month (and new year sometimes), the backed standard log files (and extra sensor log files from build 3087) are for the month that has just started, there is no back-up of the old month.
== The official version ==
Mark Crossley says the MX day reset does this (at version 3.5.x)...
<tt>
Reset midnight rain
Entering Day Reset (message about current day of month, at this stage web tag <#metdate> changes to new date)
Day Reset (message about date ending, time shown as 00:00:00 because time not defined, not because it is midnight, it might be 9am or 10am)
Run EOD custom SQL
Save dayfile entry (uses what is still in today.ini that includes old date, i.e. what is now in web tag <#metdateyesterday>)
Write monthly & yearly file entries
Write any new daily extreme records
if day of month = 1 then: copy month.ini to saved file, reset monthly figures
if day of month = 1 and month = 1 then: copy year.ini to saved file, reset yearly figures
Copy todays high/lows to yesterdays
Reset todays high/lows to current
Write today.ini & yesterday.ini
Create NOAA reports
Execute user daily external program
Process Extra EOD files
</tt>
But independent of above EOD thread that occurs on the rollover hour, the '''normal interval''' and '''hourly processes''' thread is seeking to run at same time, whether that happens at same time depends on processing capability and whether it can process multiple threads.
What actually happens in above list depends on your settings, and if your FTP interval is synchronised with the logging interval.
= Library software =
<big>For most Cumulus users, the remainder of this
Cumulus MX uses '''library''' software (i.e. software written by others and made available by the provider and often also by other content delivery nodes or 'cdn') for a lot of the standard functionality.
The library software for the admin interface and the separate library software for the standard web pages are both mostly included in the distribution zip, although some is used via a link to a cdn.
For many releases of MX, the libraries included were very obsolete. However, Mark Crossley, the current developer, said the following on 30 Sept 2019:
"Chasing the latest versions of all the packages for the sake of it is a thankless task, and requires considerable effort to regression test each update. I am only updating packages when required to fix issues or for platform compatibility." Just to mention the other side of this balance. It is difficult to code an addition to MX that works with obsolete versions of libraries. All documentation provided by providers of the libraries relates to current versions of the packages (and what is documented to work now, often will not work with obsolete versions). The documentation for the packages that are no longer supported is only available in archive sites if available at all.
By June 2021, MX development had updated the included library software. Sometimes, trying to incorporate a more recent module, made MX have problems, and so some changes had to be regressed, and some library software incorporated is pinned to a recent version but not the latest. However, multiple changes to library software, does mean this page may not be accurate for the release you have implemented.
==Library Software for the MX engine==
===Devart===
The two files used
===FluentFTP===
===Linq===
Language INtegrated Query is used to work with sequences of items and pick the ones that are needed, putting them into output format required. MX uses two files in connection with preparing output for Twitter
There is a third Linq file for other processing, "System.Reactive.Linq.dll" which is also same in all MX releases.
===MQTT===
When MX added capability to talk to other devices using the MQTT protocol, it added this component for that optional functionality. The component was updated in February 2021, and may be updated again in future.
===Newtonsoft===
This component
However, '''SystemText''' has superseded it,and MX no longer uses it (anybody want to document when MX abandoned it?).
===Renci SSH===
This component is server connection software, it is what processes the host name, password, and so on. It is still in use in June 2021.
===SQLite3===
This is used for all interactions with the [[Weather Diary|weather diary]]. The component used remains same for all MX releases.
===HTTP===
These files handle the optional HTTP functionality, "System.Net.Http.Primatives.dll" and "System.Net.Http.Extensions.dll" have remained in use since February 2015.
===Unosquare===
The '''EmbedIO''' file is open-source software that handles the web-sockets functionality of MX. The '''Swan.Lite''' file is open-source software that handles JSON formatting and threading of tasks in MX.
== Library software for admin interface ==
#Alpaca software is effectively a programming language extension to help people design forms like those MX uses for all its settings, and as a Cumulus user you really don't need to worry about it.
#It is used for most settings screens. See http://www.alpacajs.org/ for more information. The latest version there is 1.5.27 released on 14 May 2019.
# MX
# It is believed MX updated to newer versions from February 2021, recent releases are trying to improve accessibility, so there might be another update.
===Bootstrap===
*The simplest way to think about this package is as a standard set of styling promoting easy responsive (means adapts to screen dimensions) web site design.
*To give just a few examples, it defines a standard way to represent buttons, form components, lists, navigation, and breadcrumbs.
*MX uses Bootstrap version 3.3.7, which is very restricted in what it offers. As at June 2021, MX is still using this, as it has for all previous releases
**Bootstrap version 5 is available (http://getbootstrap.com), so MX is using an obsolete library
** Bootstrap version 4.5.0 (Bootstrap 4 released as alpha in August 2015, beta in August 2017, and with fully working releases frequently from January 2018) was very widely praised for its improved functionality, and ability to work with latest jQuery and multiple modern devices/browsers.
#Thus dataTables does all the work of providing the ability to present the data in a HTML table, the functionality to move between multiple pages needed (as MX sends only up to 10 lines of a log file at a time to the admin interface).
#The free version of dataTables used by MX lacks the most useful functionality that needs a subscription licence. For example, its editing functionality requires a subscription.
There have been some updates to how MX implements its data log editors, it is unclear how much of this is due to work by MX developer and how much due to work by library developers.
===altEditor===
*The single line of fields that is result of an edit or deletion done on the modal is sent back via another api to the server (the MX engine in our case) and that then regenerates the dataTables in the state after whatever action was done, sending back again up to 10 lines for the same page as before.
*As it happens there is another JQuery dataTables editing tool, but it has not been maintained since 2012. It is found at https://github.com/NicolasCARPi/jquery_jeditable, but the documentation is now only available in an archive at https://web.archive.org/web/20200615000000*/https://appelsiini.net/projects/jeditable. It is designed for editing table cells, so it does not involve any pop-up dialog.
There was some exploration of alternatives during May 2020 (to deliver in-line editing), but MX is still using AltEditor in June 2021.
===datepicker===
===editable grid===
* As the name perhaps suggests MX only uses this for the extra web files screens where you can make selections within a grid like interface.
* I suspect it could enhance some other functionality in the future.
* During Spring 2021, there were some accessibility improvements, but no alternative library has been identified.
===handlebars===
# Put simply this is a simple HTML generator based on templates.
# My exploration of the files in '''Interface''' failed to discover how "handlebars" is used.
===x-editable===
===jQuery===
# The admin interface
#
Note about older version previously used:
# Of all the old versions of jQuery to choose, MX had picked the only version that the developers withdrew due to an error when they released it.
# Version 1.9.1, has a serious error in its code, because the developers accidentally combined code from two significantly different versions when they created the release file.
#*This reveals itself in two ways:
#*# The error handling does not work.
#*# It tries to load another script that does not match.
# Consequently, the developers quickly removed it, but it remained available from Contents Delivery Nodes, which is where MX
# Not surprisingly, the authors of jQuery strongly advise all 1.9.1 users to move to a later version.
#* Unfortunately, there are interdependencies between all the library code used by MX, so you cannot simply update this component (see next library item).
===Jquery Template===
* MX continues to use an old version of jQuery template, which was withdrawn many years ago.
*It was originally available from jQuery downloads, but they now offer '''jsRender.js''' for this functionality.
* It basically is used to bind the contents of objects (like array elements) into particular locations within HTML.
===Highstocks===
Most of the libraries included in MX are directly included in the MX release distribution zip. The odd one out is '''Highstocks''' (that includes HighCharts) where for early MX releases the code was included, but from 3.5.0 the code is loaded from a Contents Distribution Node (CDN).
* Inclusion of loading from CDN means that the Charts page in the admin interface will only work when there is an internet connection working to permit download of this software
*If you need to view your admin interface where an internet connection is not available:
Then you need to edit the interface file...
<pre><script src="webfiles/lib/highstock/js/highstock.js"></script>
<script src="webfiles/lib/highstock/js/themes/grid.js"></script></pre>
#Each release from 3.5.0 onwards has selected a particular release to load from the CDN, which sometimes is, and sometimes is not, the latest release.
#* As at June 2021 (MX release 3.12.0), Highstocks 9.1.0 is the pinned release, which is not the latest release.
#* (Earlier MX releases, pinned to earlier Highstocks releases, although it was latest release for MX 3.11.x releases)
== Library software for your web server ==
#'''Highstock'''
#*
#*
#* Since 3.10.0, the new default web pages are a one-off upload, and they use the CDN, there is no copy included in the '''webfiles/lib''' folder.
#'''jQuery'''
#* Be aware that many MX release distribution
#*# Up to MX 3.9.7, '''gauges.htm'''
#*#*
#*# Up to MX 3.9.7, '''trends.htm'''
#*#*Ironically, the old version of jQuery that
#* The MX 3.10.0 announcement says that the new default web site uses the latest jQuery, although it does not mention a specific version.
#'''Steel Series''' this is treated as library software, as it is copies of that separate product by Mark Crossley.
#* Most of the files are exactly as that was in revision 0.14.13 made 30 January 2015.
#* '''gauges.js''' has one tweak for MX, it defaults to not having chart rollovers (for Cumulus 1, this file had default to showing the images of graphs that were uploaded by Cumulus 1).
| |||