MX Administrative Interface: Difference between revisions

m
(12 intermediate revisions by one other user not shown)
 
{{Template:WorkInProgressBanner}}
<div style="background: LemonChiffon;padding:5px; margin:2px;">
 
[[File:Crystal Clear info.png|40px]] This document is 'Work In Progress' so content may not be complete or accurate!
</div>
 
=Terminology=
 
This Wiki page has the title "MX administrative interface". That name is fully descriptive of the purpose of the functionality documented on this page. In subsequent references this is shortened to "admin interface".
 
Put simply this means the various pages you see in a browser that allow you to look at weather data and change settings.
 
When Steve Loft made his original cumulus software (legacy cumulus 1) available for others to use, it was natural for him to use "user interface" as a collective term for all the [[Cumulus_Screenshots|various screens]] that he included with that software.
When he worked on Cumulus 2 alpha builds, he needed to explain how the design of his new software was different, and he talked about it separating "engine" and "user interface". Basically, the engine read information from the weather station, calculated derivatives, and monitored extreme records. The user interface was a web server generated by the engine, here you could amend settings, and see those weather derivatives (the alpha Cumulus 2 never had ability to feed any information to an external web server).
 
Thus Steve Loft used the same terminology (engine and user interface) for his Cumulus 3 beta (also known as MX). When Mark Crossley took over development and brought MX out of beta, he added much more to the web server that the engine generated, and he talks about "the code" where Steve used "engine" and he uses "admin interface" for the enhanced collection of web pages generated by "the code" allowing you to do many administrative tasks like correcting log files (both data logs and extreme record logs). TheSince newthen, Mark has redesigned almost every page that Steve Loft created, so there is effectively nothing of the old "user interface" alsoleft, displaysand your"admin datainterface" intherefore describes the new morefunctionality waysbetter.
 
=How to see and use the Admin Interface=
 
Having set the station type, and other settings, you will need stop Cumulus MX and start it again.
 
If you have chosen to download and use the alternative Admin Interface (AI) it will be available using the url: <tt>http://localhost:8998/ai.cmx/</tt>. All the information on this page also applies to the AI. For other information on the AI visit the [[Alternative_Interface|Alternative Interface]] page.
 
=What does the admin interface contain?=
The admin interface web pages that Mark has either added, or redesigned significantly, are those that allow you to edit the data log (.txt) files, to edit the extreme record (.ini) log files, and to input and modify configuration settings. These have changed a lot as Mark has developed MX, and the documentation of these later may not be kept up to date with the latest changes.
==Weather pages==
 
===Dashboard===
 
Mix of tables and gauges to show current conditions, and alarms
 
===Now===
 
Current data in tabular format
 
===Gauges===
 
Current data in [[SteelSeries Gauges]] format
 
===Charts===
 
[[Highcharts - Recent|Recent]], Selectachart, and [[Highcharts - Historic|historic]] graphs
 
===Today/yesterday===
 
Data for today-so-far, and yesterday in tabular format
 
===Records===
 
Data for this month-to-date, this year-to-date, all January months ... all December months, and all-time in tabular format
 
== The API interface ==
 
== The MQTT interface ==
 
Until this section is written, please see [[Cumulus.ini (MX 3.0.0 to 3.7.0)#MQTT]] for the information you can put into settings, and where to enter it.
 
== The Data Log Viewing and Editing interface ==
[[File:Crystal Clear info.png|40px]] This section was written around the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for thisthese pagesections, itthey may even need a redesign so it can correctly cover both past and more recent releases!
</div>
All settings are stored in [[Cumulus.ini]], so when you stop and restart MX, it can continue without you entering settings again. On that linked page, the settings are explained for each settings page, explaining which entry in the configuration file is affected.
 
Adjusting the majority of the settings is best done using these MX "admin interface" screens simply because for some settings the interface does validation (whilst editing the file directly could introduce invalid settings), you will see that '''Settings''' is the penultimate option in the navigation bar, and it has a drop down for the various settings screens that are now described. [[File:Settings Menu.png|right]]
If you attempt to set these settings by directly editing the file where they are stored, there is a danger of either making a typo or of choosing an illegal value for a particular attribute.
 
ThereFor areolder howeverMX releases, some '''read only''' settings that can not be found in any of the setting screens, for these MX cannot set the values, it can only read them. As MX cannot set the values, you need to edit the [[Cumulus.ini (MX_3.0.0_to_3.7.0)]] file directly, and the referenced Wiki page identifies read-only settings that can only be adjusted by adding parameters directly in the file. The configuration article lists the read-write settings as well, and tells you what values are accepted for those attributes, and also explains some of the differences in the settings available between Cumulus 1 and MX.
'''Note that if you change settings''', that '''some''' settings do not take effect while MX is running, while other settings do take effect instantly (The developer has not provided a list anywhere of which settings do, and which do not, take effect immediently, although sometimes a release notice mentions this for a new setting) - anyway, you ''may'' need to restart Cumulus MX to get the new setting picked up. When you exit MX, it saves the read-write settings in [[Cumulus.ini]], and when you restart it it uses the read-only, and read-write, settings it reads from that file.
 
=== Station Settings ===
 
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section was last updated for the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for this section,
 
recent releases have totally changed the content of all settings pages in the admin interface,
 
consequently, the whole page may even need either a replacement set of pages, splitting of this page into multiple pages, or just a redesign of this section, for more recent releases!
</div>
 
 
 
Each setting has a hint beside it (with a small 'i' for information before each hint). If you have used [[Cumulus_Screenshots#Station|Cumulus 1]], the layout and section headings will be familiar. No settings takes effect until '''Save''' button pressed.
'''Extra Sensors''' - any sensors whose readings are logged in the standard log file are not '''extra'''. You tick here if you want Cumulus to log sensors using the extra sensors log file. Both log files are known as monthly logs in that a new log is created for each new month. (This is nothing to do with the '''special log''' that Cumulus 1 maintained for multiple temperature and humidity readings, as it is not available in MX).
 
'''Debug logging''' is used to switch on extra debugging information (about what Cumulus does in its processing) in the [[MXDiags_folderMXdiags_folder]] log file. It only remains on until either it is turned off here or Cumulus is closed. Use [[Cumulus_MX#Parameter_for_adding_debugging|a parameter '''-debug''' for adding debugging]] when you start Cumulus if you want the debugging to persist.
 
'''Data logging''' is used to switch on extra debugging information (about interaction between weather station and Cumulus) in the [[MXDiags_folderMXdiags_folder]] log file. It only remains on until either it is turned off here or Cumulus is closed. Use [[Cumulus_MX#Parameter_for_adding_debugging|a parameter '''-logging''' for adding data logging]] when you start Cumulus if you want the data logging to persist.
 
'''Stop second instance''' Invokes code that stops you having 2 copies of MX running at same time and conflicting.
 
=== Internet Settings ===
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section was last updated for the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for this section,
 
recent releases have totally changed the content of all settings pages in the admin interface,
 
consequently, the whole page may even need either a replacement set of pages, splitting of this page into multiple pages, or just a redesign of this section, for more recent releases!
</div>
 
 
 
All settings entered here are stored in [[Cumulus.ini]]. No settings take effect until '''Save''' button pressed. [[File:Include graph data files.PNG|right]]
Some settings don't take full effect unless, after saving the change, you restart MX. There is not yet a definitive list of which settings are only read when MX is started, but for example from build 3048 onwards the '''enable/disable Realtime FTP''' setting does not need a restart, but for earlier builds of MX it does.
 
All retain their settings when MX is restarted. No settings take effect until '''Save''' button pressed. This includes '''FTP logging''' in '''Web/FTP settings''' section, (it is not in this image as it is further down), which is used to add additional information to [[MXDiags_folderMXdiags_folder]] about standard File Transfer Process actions; it will persist across stopping and restarting MX, so you must switch it off here (or with MX stopped within [[Cumulus.ini#Section:_FTP_site|Cumulus.ini '''FTP site''' section]].
 
The MX settings on this web page have a lot of similarities with the [[Cumulus_Screenshots#Sites.2FOptions_Tab|Cumulus 1 settings]]
*some defaults are different in the two flavours.
 
 
While Cumulus 1 only supports standard FTP, MX supports tha,t plus SFTP and FTPS. Which you select depends on your web site, it might be that you used a tool to manually upload files and so you can copy settings from that tool into the MX settings.
==== Admin Interface: Settings Menu: Internet settings: '''Web/FTP settings''' ====
 
{{Version badge Mx}}[[File:Include graph data files.PNG|right]]
#Click on this heading to expand settings as per illustration.
#''Auto update''
#*Tick this to enable updates to a web server by MX. (Don't tick it if you don't have any web space).
#''Include standard files''
#* Standard files are the web page templates in the web folder, each file as a name ending in "T.htm". Tick here if you want those files to be processed by MX and uploaded at standard web interval to the host and directory we have set earlier.
#''Include graph data files''
#* These are files with an extension ".json" and MX generates these automatically, storing them in the web folder. Tick here (as arrowed) if you want those files to be processed by MX and uploaded at standard web interval to the host and directory we have set earlier.
#''Include Moon image file''
#*We first need to set (later on this same settings page) that MX is to use system drawing to produce "moon.png" in the same web folder from "MoonBaseImage.png" in that folder. The base image is of a full moon, MX uses system drawing to generated a masked version of this image every hour that reflects the current phase of the moon and stores that in "moon.png".
#*With "moon.png" being generated, we can tick here to include the new image in an upload by FTP every hour.
#''ActiveFTP mode, FTP rename, Delete before upload''
#*Please be guided by the tips below these selections on the settings page.
#''UTF-8 encoding''
#*Cumulus supports just two encodings, please see [[Webtags#Encoding|Encoding]] section in another article for more information. Here just tick this selection for standard web pages.
#''FTP logging''
#*Normally, this is left unticked, but if you want to check MX is uploading (and you use the simple FTP protocol), you can tick this for every FTP transfer to be logged to [[MXdiags_folder]].
#''Upload interval''
#*Standard web pages are updated on the hour and every x minutes thereafter, where x is the number you enter here. Most people would choose 10, 15, 20, or 30, here depending how much uploading they want, and how up to date they want the displayed information to be.
#*As an aside, if you are not using the standard web pages, many [[:Category:User Contributions|third party]] web pages use ajax (don't worry about what that is) to allow some of the web page content to be updated far more frequently than the actual web pages get uploaded.
#The realtime settings are only needed for the gauges page and settings depend on your MX version, right hand picture is Cumulus MX settings screen)[[File:Cumulus MX realtime settings.png |Right]]
 
From build 3042, MX automatically uploads the realtimegauges.txt file.
 
Note that the realtimegaugesT.txt file for MX is slightly different to the one for Cumulus 1, and it is important to use the one supplied with MX for MX.
 
You have now told Cumulus how to update your web space with the [[Customised_templates#The_Standard_Templates |Standard Cumulus Template]] files for the web.
 
====ADDITIONAL INSTRUCTIONS FOR OLDER MX BUILDS:====
 
Prior to build 3042, you also need to specify an extra file in the table for the steel series gauges page to work:[[File:Extra web settings.png | Right]]
#'Local filenames' column
#*Enter the path and filename for the realtimegaugesT.txt file where shown by red box. This will normally be web\realtimegaugesT.txt on Windows, and web/realtimegaugesT.txt on other platforms.
#'Remote filenames' column
#*The green box shows where you must type the path to where you want the web page to appear (i.e. where the other web pages are uploaded to) ending with the file name '' realtimegauges.txt''. Typically the path will involve specifying the directory you entered on the 'Sites/Options' tab (see the 'Web Site' settings step 3 for that tab above).
#'Process?' column
#*Select this (ringed in purple), as ''realtimegaugesT.txt'' contains web tags and needs to be processed to create the remote file.
#'Realtime?' column
#*Select this (ringed in purple), only ''if you want the file to be created at whatever interval you have defined for real-time updates'' (see 'web settings' point 7 above for where you did that); otherwise it will be updated on your web site at the normal updating interval.
# 'FTP?' column
#*Select this (ringed in purple) if the destination is remote (don't select if the destination is local).
#'UTF-8?' column
#*This is irrelevant for this file.
 
==== Other Internet Settings ====
While Cumulus 1 only supports standard FTP, MX supports that plus SFTP and FTPS. Which you select depends on your web site, it might be that you used a tool to manually upload files and so you can copy settings from that tool into the MX settings.
 
Like Cumulus 1, MX has an '''External Programs''' section. Here you can enter a command and (in separate box) parameters for 3 possible timings (at real-time, at interval, and at end of day). Typically, on a windows device you would enter the name of a batch file (filename ends in .cmd). On a device running Linux, it could be a shell command file (ends in .sh) or indeed a command like "php" to run a php script whose name is specifed in parameters box. The final parameter might be preceded by ">" to direct the output to a log file.
# change some paths in local column, (if your Cumulus 1 and your MX locations are different)
#*if you have moved to a Raspberry Pi, or other Unix-derived operating system, remember that path names in Microsoft Windows operating systems use "\" as directory separator, but all other systems use "/".
#*There is more advice available at [[Setting_up_Raspberry_PiMX_on_Linux#Configuration_files]].
# untick one column, and tick another, now that '''End of day''' is an option for the timing as well as real-time and (normal uploading/ftp) interval.
# edit some templates (local files) where the process column is ticked because of [[Webtags|Web tags differences]] (some output modifiers are interpreted differently), you will need to revisit every web tag in every template to check whether the output format will need to be added, or amended, to give the output you want.
[[File:NOAA settings.png|right | 200 px]]
 
The various settings available on this screen are explained [[Cumulus.ini#Section:_NOAAOptional_Report_Settings|here]].
 
Just a quick reminder here that while Cumulus 1 is case insensitive for the code for the different ways to specify a month, MX only accepts upper case ('MM' for digits, 'MMM' for 3 letter month etc.), read more about [[Reports_folder#NOAA_style_Report_Naming|the naming here]].
 
=== MySQL settings ===
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section was last updated for the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out any updates needed for this section,
 
recent releases have totally changed the content of all settings pages in the admin interface,
 
consequently, the whole page may even need either a replacement set of pages, splitting of this page into multiple pages, or just a redesign of this section, for more recent releases!
</div>
 
 
Cumulus MX includes functionality not in Cumulus 1, and this is one example of a new feature. It is designed to automate updating of MySQL databases whose schema has each table based on one of the Cumulus log files. This MX feature was developed from [[ImportCumulusFile|this script]] for Cumulus 1.
# Now move down the screen and click the '''Save''' button, and wait for MX to pop up '''Settings Saved''' message.
 
===== Another table unpdatedupdated at an interval measured in seconds =====
 
*6. ''Custom upload - seconds interval''
 
=== Alarms ===
 
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section was last updated for the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for this section,
 
recent releases have totally changed the content of all settings pages in the admin interface,
 
consequently, the whole page may even need either a replacement set of pages, splitting of this page into multiple pages, or just a redesign of this section, for more recent releases!
</div>
 
 
This is identical to Cumulus 1 functionality, apart from using a new default location for the files "\CumulusMX\interface\sounds", and the list of alarms available is extended in MX compared to Cumulus 1.
 
=== FTP Now ===
 
 
<div style="background: LemonChiffon;padding:5px; margin:2px;">
[[File:Crystal Clear info.png|40px]] This section was last updated for the MX release in July 2020; that is no longer latest!
 
Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for this section,
 
recent releases have totally changed the content of all settings pages in the admin interface,
 
consequently, the whole page may even need either a replacement set of pages, splitting of this page into multiple pages, or just a redesign of this section, for more recent releases!
</div>
 
 
This is similar to the option in the file menu of Cumulus 1 to do an update now. Depending on which build of MX you are using, the functionality varies. On latest build it does whatever updates are set up to happen at normal updating interval whether these are by FTP to your web site, or by copying files between local and remote filenames with path (although both could be on same device).
334

edits