Category:Cumulus MX: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Category:Cumulus MX (view source)

Revision as of 06:44, 4 August 2020

6,567 bytes added ,  06:44, 4 August 2020
m
→‎Library software
(11 intermediate revisions by 2 users not shown)
Line 112: Line 112:
== Documentation for MX ==
== Documentation for MX ==


=== Cross reference to article on [[Moving from Cumulus 1 to MX]] (includes general issues regarding running on Windows) ===


=== Cross-reference to [[What to do when I have a problem with MX]] ===
You may be reading this article on MX as a Cumulus 1 user considering moving to MX, if so then the separate article linked from the heading to this section will interest you as it explains all issues when moving from Cumulus 1 to MX.
 
You may have no interest in Cumulus 1, but you are using MX on Windows, if so you still may find the separate article linked from the heading to this section will interest you as it gives a lot of information about installing Cumulus MX on Windows.


The text that was here has been moved to a separate article, that makes it more accessible, please see [[What to do when I have a problem with MX|What to do when I have a problem with MX article]]
Finally, if you are using MX on another device, then ignore the link in the heading to this section.


=== Cross reference to issues relating to Cumulus on devices running Windows, including [[Moving from Cumulus 1 to MX]] ===
=== Cross reference to article on [[Updating MX to new version]] ===


This has also been moved to a separate article, so those not interested don't need to read it.
Whether you have not updated for a long time, or simply wonder whether you are updating the easiest way, follow the link in the heading for this section, to an article that focusses on all to do with updating from one MX version to another.


Please note that the same article [[Moving from Cumulus 1 to MX|Issues re Cumulus 1 and MX]], covers a lot of information about installing Cumulus MX on Windows; as well as issues when moving from Cumulus 1 to MX.
Critically, this linked article contains advice '''both''' for those updating each time there is a new release available '''and''' for those using an old version (perhaps when MX was still in beta) wishing to update to a new version skipping some in-between versions and need advice on whether to do it in multiple steps.


=== Cross reference to [[Cumulus MX FAQ]] ===
=== Cross reference to [[Cumulus MX FAQ]] ===


A new FAQ for MX has been started at [[Cumulus_MX_FAQ|another page]].
A new FAQ for MX has been started at [[Cumulus_MX_FAQ|another page]]. As I add the link here, the Cumulus MX FAQ is in a mess, but hopefully someone will have time to sort it out.


Many MX specific questions, such as those related to installation are now covered by the updated text on this "Cumulus MX" page.
Meanwhile most MX specific questions are now covered by the updating of text on this "Cumulus MX" page.


=== Cross reference to [[MX Issues]] ===
=== Cross reference to [[MX Issues]] ===


The [[MX Issues|Cumulus MX Known Issues]] article is based on [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=12943 Steve Loft's forum post], but there has been an attempt to update the contents. Anyone willing to check it and do a further update?
The [[MX Issues|Cumulus MX Known Issues]] article was based on [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=12943 Steve Loft's forum post] so based on an early beta version of MX, and there has been minimal attempt to update the contents as MX has been developed further and come out of the original beta. <big>Anyone willing to check the linked article and do a further update?</big>
 
 
=== Cross-reference to [[What to do when I have a problem with MX]] ===
 
The text that was here has been moved to a separate article, that makes it more accessible, please see [[What to do when I have a problem with MX|What to do when I have a problem with MX article]]


=== Cross reference to [[MX Administrative Interface|Administrative Interface]] ===
=== Cross reference to [[MX Administrative Interface|Administrative Interface]] ===
Line 137: Line 145:
This requires a whole topic to itself, and indeed it has an article to itself, reached from link in heading for this section.
This requires a whole topic to itself, and indeed it has an article to itself, reached from link in heading for this section.


=== Cross reference to article on [[Updating MX to new version]] ===


Because If you are doing an update you don't want to read a long article, this topic has an article to itself, reached from link in heading for this section.
=== Message from Steve Loft about documentation ===
 
''The following was written by Steve Loft when he first made his MX beta available to Cumulus users. Although somewhat outdated it is preserved here.''


=== Message from Steve Loft about documentation ===
There's quite a lot to read before you start - please do read all of this page and all the references it mentions, most of it is very important.  
There's quite a lot to read before you start - please do read all of this page and all the references it mentions, most of it is very important.  


Line 264: Line 272:
For Windows 10 you need version 4.8 or later, this should already be installed by your windows update feature.  The .Net download for version 4.8 should be here https://dotnet.microsoft.com/download/dotnet-framework/net48.
For Windows 10 you need version 4.8 or later, this should already be installed by your windows update feature.  The .Net download for version 4.8 should be here https://dotnet.microsoft.com/download/dotnet-framework/net48.


Cumulus MX initiates a web server, to do this it may need administrative access, consequently to avoid having to run MX as an administrator you can issue a command that allows all users to bind to port 8998 which is the web server it initiates (this is used for the Cumulus MX user interface). Note that if you plan to change the interface port by using the port parameter in your launch of MX, you should change the 8998 to whatever port you are planning on using. To enter the command, first open a command window as administrator. One way to do this is to right click the windows symbol at the start of the windows task bar. The option to choose there (on windows 10) is '''Windows PowerShell (admin)''', but an option called '''Command Prompt (Administrator)''' will also work. Once that opens a new window type:
For those who downloaded the first MX Beta in January 2015, the code was only experimental and that version had to be run by a Windows Administrative User, but Steve Loft soon improved the code and now none of the code requires any elevated rights and it can be run by a normal user (or  a user with administrative rights) without needing to be started by '''Run as administrator'''.
 
However, Cumulus MX initiates a web server, which is what runs the [[MX_Administrative_Interface|Admin Interface]]. To access that, all users need to be given elevated rights to the port on which the web server runs. By default this is port 8998, so that is used in the example below of the one-off command needed to give all users access to the port. You can use a '''-port=nnnn''' parameter when starting MX to make it use another port, if you use that then the command below needs revising accordingly.
 
To enter the command, first open a command window as administrator. One way to do this is to right click the windows symbol at the start of the windows task bar. The option to choose there is dependent on some settings which determine what appears when you right click:
*the normal default on Windows 10 is '''Windows PowerShell (admin)''',
*the normal default on earlier versions of Windows is  '''Command Prompt (Administrator)'''  
*an alternative is '''Windows Terminal'''
Whichever of these you can use, the result is it opens a new window on your monitor with a prompt for typing. In that window type the command:
<pre>
<pre>
netsh http add urlacl url=http://*:8998/ user=\users
netsh http add urlacl url=http://*:8998/ user=\users
</pre>
</pre>


You only need to do that once. After than you can initiate MX from any user, you don't need to run as administrator.
You only need to do that once. If you do not issue this command, you do need to start MX with '''Run as administrator''', otherwise you may have difficulty in using the Admin interface.
 
Talking about command windows, if you want to check that the port is open for listening (i.e. able to access the admin interface) type <tt>netstat -an | findstr 8998</tt> into the command window.


Talking about command windows, if you want to check that the port is open for listening (when MX is running, the port is used for the administrative interface) type <tt>netstat -an | findstr 8998</tt> into the command window.
The admin interface URL '''http://*:8998/''' needs to have that wildcard "*" replaced by a precise location if we are to access the admin interface.  The missing part of the URL depends on how your local network is set up.  If you are accessing the admin interface on the same device as that running MX (and you don't have another web server on that device) the "*" can be replaced by "localhost", i.e. '''http://localhost:8998/''' will be used to load the admin interface into your browser.  In the more general case when you want to access the admin interface from anywhere on your local wired and wireless interface, then the "*" needs to be replaced by a string of 4 numbers representing what is called a IPv4 address (w.x.y.z) of the device you have installed MX on.


Look at your hub or router (this should have come with instructions on how to access its settings in your browser) and on one screen it should show what devices are connected to your LAN and wifi. Look for the IPv4 address, for example 192.168.1.64, it has assigned to the device where MX is running. That is what should replace the "*".  However, there is one more complication, either the Windows networking settings may change, or else your hub or router may reconfigure, both can happen at any time and both can assign a different IPv4 address to the device running MX.


After you have done this you can run CumulusMX.exe normally without Administrator rights and therefore you can create a short-cut to run MX when your PC starts (put your user name where I have put ...), the shortcut should point to T:\CumulusMX\CumulusMX.exe (where T is used here only to denote the drive on which you have installed MX as it does not need to be the same as where your operating system is):
To give your Computer a fixed address for the MX admin interface,
C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\CumulusMX.exe
#first find the network card via Network and Sharing Centre (Control Panel),  
With this you might want to right click on that shortcut, select properties, then you can set the starting position for the command window, the colours and font it will use, and even choose to start minimised, amongst many other selections.
#then click on Change Adapter Settings,
#then Right click on Ethernet or WiFi Adapter,
#next select Properties
# In the window that opens, right click on Internet Protocol Version 4 (TCP/IP 4),  
#Next select properties
# Onn that pop up screen tell the computer to "use the following IP address"
#Fill out the form with
#* a subnet mask of 255.255.255.0 and  
#*gateway address between 192.168.1.1 and 192.168.1.254 (depending on the address of your hub/router).


Look at your hub or router (this should have come with instructions on how to do this in your browser) and on one screen it should show what devices are connected to your LAN and wifi. Look for the IPv4 address (w.x.y.z) of the device you have installed MX on, for example 192.168.1.64. Then give your Computer a fixed address  for MX user interface by finding the network card via Network and Sharing Centre (Control Panel), click on Change Adapter Settings, then Right click on Ethernet or WiFi Adapter, select Properties and in the window that opens right click on Internet Protocol Version 4 (TCP/IP 4), and select properties and on that pop up screen tell the computer to "use the following IP address and fill it out with a subnet mask of 255.255.255.0 and gateway address between 192.168.1.1 and 192.168.1.254 (depending on the address of your hub/router).
==== Setting up for either manual or automatic running ====
==== Setting up for either manual or automatic running ====


There are 3 ways on Windows to create a way to run MX, you can't just click on the executable in file manager, because Windows needs to be told the path for loading all the related .dll files.
 
To run Cumulus MX, Windows needs to know
#which '''.exe''' you want to run
#the path where all the required '''.dll''' files are located
 
Therefore it is best to always start MX using what Windows calls a '''shortcut''', because when creating the shortcut you can enter all the required information into the properties.  If you want MX to automatically start whenever you log into your PC, then the place to store your shortcut is <tt>C:\Users\...\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\Run_CumulusMX</tt>.  Don't forget to put your Microsoft username where I have put ...
 
With this you might want to right click on that shortcut, select properties, then you can set the starting position for the command window, the colours and font it will use, and even choose to start minimised, amongst many other selections.
 
There are 3 ways on Windows to create a shortcut to run MX, as mentioned above you can't just click on the executable in file manager, because Windows needs to be told the path for loading all the related .dll files.




Line 606: Line 641:
= Library software =
= Library software =


Cumulus MX uses library software for a lot of the standard functionality. The library software is largely included in the distribution zip.
For most Cumulus users, this whole section can be skipped, but I have included it for those few users who have a technical slant and might want to understand more.
 
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.
 
Many of the libraries included by MX are 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 these 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.
 
==Library Software for the MX engine==
 
The distribution zip contains various '''.dll''' files and these are the libraries used by MX itself.
 
===Devart===
 
The two files used are both related to the database functionality of MX.
 
===FluentFTP===
 
As the name suggests, this is used by MX for controlling the file transfer functionality. This component has been updated at certain MX releases, see the announcements for details.
 
===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.
 
===MQTT===
 
When MX added capability to talk to other devices using the MQTT protocol, it added this component for that optional functionality.
 
===Newtonsoft===
 
This component is used for processing JSON strings. It is a very popular choice for developers, and used therefore very widely. However, '''SystemText''' has superseded it, so MX is using an obsolete method.
 
===Renci SSH===
 
This component is server connection software, it is what processes the host name, password, and so on.
 
===SQLite3===
 
This is used for all interactions with the [[Weather Diary|weather diary]].
 
===HTTP===
 
These files handle the optional HTTP functionality.
 
===Unosquare===
 
The EmbedIO file is open-source software that handles the web-sockets functionality of MX. The Swan file is open-source software that handles JSON formatting and threading of tasks in MX.


== Library software for admin interface ==
== Library software for admin interface ==
As the following sections reveal, MX uses external libraries rather than writing its own code whenever possible.
*However, that does not mean MX is good at meeting development standards.
*MX only implements small parts of the functionality of most libraries, the minimum to make a feature work, not all the features available to make it work well
*MX does not use the latest versions of libraries
*MX does not attempt to obey guidance for good user interaction, and although validation is being added, many parts of MX do depend on user understanding what is valid
*MX does not make provision for screen readers and other accessibility aids.


===Alpaca===
===Alpaca===
Line 618: Line 707:
===Bootstrap===
===Bootstrap===


#Also known by some as ''Twitter Bootstrap'' which gives a clue as to its origins as an internal tool for those building Twitter, that company still keep making updates as it is now the most popular styling library of all those available widely.
#Also known by some as ''Twitter Bootstrap'' which gives a clue as to its developer and to its origins as an internal tool for those building Twitter, that company still keep making updates as it is now the most popular styling library of all those available widely.
*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.
*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.
*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 (http://getbootstrap.com), which is very restricted in what it offers
*MX uses Bootstrap version 3.3.7, which is very restricted in what it offers
** The current 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) has been very widely praised for its improved functionality, and ability to work with latest jQuery and multiple modern devices/browsers.   
**Bootstrap version 5 is available (http://getbootstrap.com), so MX is using an obsolete library
*MX does not implement colouring text according to what it represents (primary, secondary, information, warning etc.), nor does MX obey modern HTML standards as it makes no provision for screen readers and other accessibility aids.
** 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.   
*MX does not implement key features of Bootstrap like colouring text according to what it represents (primary, secondary, information, warning etc.)


===dataTables===
===dataTables===
#When MX sends out multiple lines of a log file to view or edit, the application programming interface (api) that transfers the information from the MX engine sends it in dataTables format for display on the web page in the admin interface.
#When MX sends out multiple lines of a log file to view or edit, the application programming interface (api) that transfers the information from the MX engine sends it in dataTables format for display on the web page in the admin interface.
#Thus dataTables does all the work of providing the ability to move between multiple pages needed to allow MX to just send 10 lines of a log file at a time to the admin interface.
#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, editing functionality requires a subscription.
#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.


===altEditor===
===altEditor===


*This is an editing tool that can read what is in dataTables, create what it calls a modal (a pop-up dialog) where rows can be added, edited or deleted individually.
*This is an editing tool that can read what is in dataTables, create what it calls a modal (a pop-up dialog) where rows can be added, edited, or deleted individually.
** MX when it added editing of log files at version 3.4.5 - Build 3069 (Friday 13 March 2020) adopted this software as it was free (although Mark Crossley said in his release notice: '''"The main thrust of this release is to add some log file editing capability to Cumulus MX.  It works on all three log file types, but it is fairly basic at present. You can edit or delete lines in the files.  The editing has to be done via pop-up dialog.'''  
** MX when it added editing of log files at version 3.4.5 - Build 3069 (Friday 13 March 2020) adopted this software as it was free (although Mark Crossley said in his release notice: '''"The main thrust of this release is to add some log file editing capability to Cumulus MX.  It works on all three log file types, but it is fairly basic at present. You can edit or delete lines in the files.  The editing has to be done via pop-up dialog.'''  
**'''I only found two libraries that support JQuery dataTables editing, one is very comprehensive - but costs $$$ - the other is free.  The free version does not currently support in-line editing of the table which is a shame.'''
**'''I only found two libraries that support JQuery dataTables editing, one is very comprehensive - but costs $$$ - the other is free.  The free version does not currently support in-line editing of the table which is a shame.'''
Line 680: Line 771:
===SteelSeries===
===SteelSeries===


MX uses a hacked version of the [[SteelSeries Gauges|steel series]] library described elsewhere for all the gauges (see dashboard and gauges tabs) in MX.
MX uses a modified version of the [[SteelSeries Gauges|steel series]] library made available by Mark Crossley for all the gauges (see dashboard and gauges pages of the admin interface) in MX.
 
 


===Highstocks===
===Highstocks===
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/6807...7017"

Navigation menu