5,838
edits
MX Administrative Interface: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
→Changing Settings
| (5 intermediate revisions by the same user not shown) | |||
| Line 4: | Line 4: | ||
</div> | </div> | ||
#Type the URL which is displayed (when MX starts running) into your browser (replace the * with the IP address, or use 'localhost') and the '''admin interface''' should appear. | =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). | |||
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 administrative tasks like correcting log files (both data logs and extreme record logs). The new interface also displays your data in more ways. | |||
=How to see and use the Admin Interface= | |||
#Type the URL which is displayed (when MX starts running) into your browser (replace the * with the IP address, or use 'localhost') and the '''admin interface''' should appear. | |||
# As the admin interface can both display and change settings, it must not be exposed on the internet. | |||
# However, it is available on the device running the MX code (engine). | |||
#*If the only web server running is the one generated by MX, you can replace the "*" shown by <tt>localhost</tt> | |||
#The admin interface is also available to any device connected to your local (wired or wireless) network. | |||
#*In this case, what you type might be something like <tt>http://192.168.1.xy:8998</tt> | |||
#** You may need to look at your hub or router to see what to use for x and y as they represent the device where MX is running. | |||
#*If this is a 'clean' installation, ''i.e. you don't have an existing [[Cumulus.ini]] file defining station type and units to be used'', the first thing you will need to do is to go to the '''settings''' screen. | #*If this is a 'clean' installation, ''i.e. you don't have an existing [[Cumulus.ini]] file defining station type and units to be used'', the first thing you will need to do is to go to the '''settings''' screen. | ||
#When that page is displayed it always shows the options to set the station type and units. | #When that page is displayed it always shows the options to set the station type and units. | ||
| Line 10: | Line 28: | ||
#Now go to bottom of this page and click the 'Save' button. | #Now go to bottom of this page and click the 'Save' button. | ||
Having set the station type, and other settings, you will need stop Cumulus MX and start it again. | Having set the station type, and other settings, you will need stop Cumulus MX and start it again. | ||
=What does the admin interface contain?= | |||
Essentially, the admin interface contains some web pages allowing you to view your weather data locally (there is an option in MX to upload data to a separate web server that might be provided externally). The data shown is provided via an "application programming interface" or '''api''' and that is described next. | |||
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 == | == The API interface == | ||
The current data is transferred from the MX engine to the Admin interface as a JSON string accessed via a Application Program Interface (api) | The current data is transferred from the MX engine to the Admin interface as a JSON string accessed via a Application Program Interface (api). | ||
Many browsers (e.g Firefox) allow you to specify the type of a file you want to view. So if you specify json as the type this will make the browser show it in a long but fairly readable format. | To see the full content of the api for an individual web page in the admin interface, | ||
#type into your browser the same IP reference as for the admin interface and | |||
#add a few more items | |||
#*i.e. something like <tt>http://192.168.1.x:y/api/data/currentdata </tt> for the api that is how the current data (now.html) page in the admin interface gets its data | |||
#there is more information on [[Cumulus_MX_Local_API|Local API page]]. | |||
Again you may need to look at your hub or router to see what to use for x and y as they represent the device where MX is running. | |||
Many browsers (e.g Firefox) allow you to specify the type of a file you want to view. So if you specify '''json''' as the type, this will make the browser show it in a long but fairly readable format. | |||
Each table cell (on a admin interface page that lists your weather data in a tabular format), contains a span element. Each span element is given an '''id attribute''' whose value matches one of the items in the json stream coming via the api. | |||
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. | 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. | ||
| Line 22: | Line 56: | ||
===Technical aside=== | ===Technical aside=== | ||
When reading the support forum (or articles in this Wiki), you may see mention of AJAX and | When reading the support forum (or articles in this Wiki), you may see mention of AJAX and Web Sockets. They are both methods of exchanging information between a web page and the data source, and explained below. | ||
Asynchronous JavaScript and XML (AJAX) is the widely used name for what Microsoft invented as '''XMLHttpRequest''' (late 1999, Internet Explorer 5.0) | In the Cumulus MX context, they represent two ways of updating the data shown on an admin interface page like '''now.html''' or ''todayyest.html''. | ||
*Steve Loft's MX beta builds used different ports for the two methods, and allowed you to pick which ports were used and which way was used. | |||
*Mark's builds use the same port for both methods, although there is still an optional parameter (when issuing the command to run MX) that can change the port used. | |||
**The latest MX releases use web sockets for updating admin interface pages that you have open, as the "engine" is coded to send updated data on a regular interval (less often in newer releases). | |||
'''Asynchronous JavaScript and XML''' (AJAX) is the widely used name for what Microsoft invented as '''XMLHttpRequest''' (late 1999, Internet Explorer 5.0). Now it is implemented in all browsers, and no longer purely a Microsoft feature. Put as simply as I can, it lets code (written into JavaScript) ask for updated information from the Cumulus MX engine to update the numbers on the web page. This is used in the data log editing pages to see if any line update has been successful. | |||
In the legacy Cumulus 1, for its trends.htm web page, AJAX was used to load an updated graph into the web page each time the client pressed a button requesting a graph. | |||
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. | 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. | ||
| Line 34: | Line 75: | ||
== The Data Log Viewing and Editing interface == | == The Data Log Viewing and Editing interface == | ||
<div style="background: LemonChiffon;padding:5px; margin:2px;"> | |||
[[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 this section, it may even need a redesign so it can correctly cover both past and more recent releases! | |||
</div> | |||
The '''Data logs''' tab in the admin interface, gives access to screens that can display the contents of 3 types of log files: | The '''Data logs''' tab in the admin interface, gives access to screens that can display the contents of 3 types of log files: | ||
| Line 39: | Line 85: | ||
#The [[Extra Sensor Files|Extra Sensor log File]]; there is one of these for each month - choose menu item '''Extra Data Logs''' | #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''' | #The [[Dayfile.txt|Daily Summary log file]]; there is only one of these - choose menu item '''Dayfile''' | ||
<big>This interface has changed in newer releases, and the information here may be out of date.</big> | |||
=== General points common to web pages for editing standard and extra sensor logs === | === General points common to web pages for editing standard and extra sensor logs === | ||
| Line 53: | Line 101: | ||
'''For all 3 web pages''' | '''For all 3 web pages''' | ||
<big>This interface has changed in newer releases, and the information here may be out of date.</big> | |||
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. | 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. | ||
| Line 119: | Line 170: | ||
[[File:Crystal Clear info.png|40px]] This section was written around the MX release in July 2020; that is no longer latest! | [[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 | Appeal to contributors: Please work through all MX release announcements and work out all the many updates needed for these sections, they may even need a redesign so it can correctly cover both past and more recent releases! | ||
</div> | </div> | ||
All settings are stored in [[Cumulus.ini]], so when you stop and restart MX, it can continue without you entering settings again. | All settings are stored in [[Cumulus.ini]], so when you stop and restart MX, it can continue without you entering settings again. | ||
