MX Administrative Interface: Difference between revisions

=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".

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).

=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.

=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.

   

== The API interface ==

This same api can be used to get weather data into another device, although you may prefer to use MQTT instead as that is more easily customised to just share the few weather values you might want.

===Technical aside===

WebSockets is an improvement on AJAX. While AJAX needs the client to make a request before an update can be made, WebSockets adds the option that the source can generate the request and do a remote update.  Thus when you open ''todayyest.html'', the MX engine gets a request from that web page to insert the various sub-tables into that web page. Subsequently, when WebSocket use is enabled, the MX engine sends updates with new figures, until you close the web page and a '''Connection Closed''' message is sent instead.

== The MQTT interface ==

== The Data Log Viewing and Editing interface ==

The '''Data logs''' tab in the admin interface, gives access to screens that can display the contents of 3 types of log files:

#The [[Extra Sensor Files|Extra Sensor log File]]; there is one of these for each month - choose menu item '''Extra Data Logs'''

#The [[Dayfile.txt|Daily Summary log file]]; there is only one of these - choose menu item '''Dayfile'''

=== General points common to web pages for editing standard and extra sensor logs ===

'''For all 3 web pages'''

The application programming interface only takes a copy of just 10 (or less if not all ten available) lines from log file and sends those to the admin interface.

[[File:Crystal Clear info.png|40px]] This section was written around the MX release in July 2020; that is no longer latest!

</div>

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.

   

'''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 ===

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).

'''Stop second instance'''  Invokes code that stops you having 2 copies of MX running at same time and conflicting.

=== Internet Settings ===

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.

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.  

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 "/".   

# 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]]  

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 ===

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.

*6. ''Custom upload - seconds interval''

=== Alarms  ===

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 ===

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).