CumulusUtils

Goals

The goal of CumulusUtils (abbr: Cutils) is to facilitate website creation for users of CumulusMX without exposure to coding in e.g. PHP or javascript. Having a meteo-website should not be privileged to users with great IT-skills. Making charts should not be demanding for programming skills in SQL or making it otherwise impossible to create charts without diving deep into the technique involved in CumulusMX (which actually is also the case with SQL).

CumulusUtils positions itself as a configurable application for which the understanding of how to run it and how to configure it is the most important thing to know. For configuration CumulusUtils uses cumulusutils.ini file which resides in the CumulusMX directory. If that file does not exist, it will be created. All other files related to CumulusUtils are in the utils directory.

The charts are created using HighCharts using their non-commercial license. If you want to use the charts or the Website Generator of CumulusUtils, please make yourself acquainted with this license.

Assumptions

The user is assumed to have basic computer skills and knowledge about the Operating System and directory structure. The user must also be aware of the directory infrastructure of CumulusMX and needs to be aware of the meaning of the terms webroot and FTProot and Working Directory. The user should be able to understand and edit the ini files (both from CumulusMX and CumulusUtils). The user should understand the basic functioning of CumulusMX which means the correct availability of CumulusMX is a precondition for using CumulusUtils.

Some output files can be used with Cumulus 1 but the charting possibilities rely on the availability of the JSON datafiles of CumulusMX. Therefore the use of CumulusUtils in combination with Cumulus 1 is limited. The website generator in combination with Cumulus 1 is not advised.

Output

The output of CumulusUtils consists of mainly of text files (extension: .txt) which are generated on demand. In Cutils idiom modules. These text files can be incorporated in a website the user has or is making. Ultimately when using the website generator feature, CumulusUtils generates a complete website, uploaded to the user domain and extendable through a user defined menu. When using the Charts Compiler, the user can define his own charts and place the output where he wants just like other modules.

Installation

CumulusUtils is available in a distribution which can be downloaded from the forum. In the CumulusMX directory the user must create a directory utils (case dependent) and must copy the files of the distribution (including the subdirectories) to that directory.
Then, on the domain for the website, the user needs to make two directories in the webroot: 'lib' and 'css'. In addition the distribution directory CUicons must be copied as a whole - with contents - to the webroot.
Updating CumulusUtils is done by completely overwriting the contents of the installation directory utils as if it were an installation. If you want to save the old installation, make a copy of the utils directory.

When installed you are ready to run.

So after installing you have:

The directory structure for utils on the CumulusMX machine is:

 utils			(contents in the distribution)
   |--- bin		(in the distribution (from 4.7.0 and up))
   |--- utilslog	(Created by CumulusUtils)

The directory structure for utils on the Website is:

 WebRoot		(Content uploaded by CumulusUtils)
   |--- lib		(Uploaded by CumulusUtils when in the utils dir)
   |--- css		(Uploaded by CumulusUtils when in the utils dir)
   |--- CUicons        (Manually copied once during setup)

Running CumulusUtils

CumulusUtils runs on any operating system CumulusMX runs on and it MUST run in the CumulusMX directory (as working directory). Running CumulusUtils is done from the commandline in a command window (under any OS).

CumulusUtils takes one or more commandline parameters (in short: commands) and must be like (square brackets means: optional):

               utils/bin/cumulusutils.exe [command]

If no commands are given the application responds with:

               CumulusUtils : No Arguments nothing to do. Exiting. See Manual.
               CumulusUtils Usage : utils/bin/cumulusutils.exe [args] (args case independent):
                 utils/bin/cumulusutils.exe
                     [ SysInfo ] [ Forecast ] [ StationMap ] [ UserReports ]
                     [ pwsFWI ][ Top10 ][ Graphs ][ Yadr ][ Records ]
                     [ NOAA ][ DayRecords ][ AirQuality ][ CompileOnly ]
                     | [ Thrifty ] All
                     | CheckOnly

               OR (in case you use the website generator):
                  utils/bin/cumulusutils.exe [ Thrifty ] Website

All modules mentioned in the command will be described in their own pages here on the wiki and when available will be linked from here.

The commands represent the modules the user is asking for to be generated. The output is generated to the utils directory in the CumulusMX directory. When asking for the generation of the website, the user not only gets all modules available but also an index.html file accompanied with some javascript infrastructure. Everything together then is the website which, when copied to the webroot, is ready for use.

Commands to CumulusUtils - the module names - are case independent but the author prefers Upper Camel Case (or Pascal Case).

Copying to the webroot can also be done automatically through the FTP account of the user, much like CumulusMX itself copies e.g. the realtime.txt or the datafiles to the webroot. The FTP account and domain used are the same as present in the Cumulus.ini configuration.

Additional remarks

CumulusUtils is written in C#, HTML and javascript. All HTML and javascript is embedded in the C# code and generated on execution of CumulusUtils. The cumuluscharts.js charts library was based on the original distributed with CumulusMX, probably the version a bit before April 2020 and has been modified since. With the appearance of the ChartsCompiler the name cumuluscharts.js has been preserved but the technique of creating the charts has been changed.
As CumulusUtils itself runs in the Cumulus directory, the data directory (data) is one level below. CumulusUtils currently uses - a copy of - dayfile.txt, the monthly logfiles and incidentally the alltime.ini file. It also takes information from Cumulus.ini. All output is written to the utils/ subdirectory. All logs are created in the utils/utilslog/ subdirectory.
The output of CumulusUtils consists of UTF8 encoded text files. They can be brought to your website manually through some ftp tool (e.g. WinSCP) or by using the Extra Web Files functionality in the setting of Cumulus (deprecated) or by using the Internal FTP facility.
CumulusUtils can output for many languages. See the specific page on language in CumulusUtils.
In case of problems there exists a Cumulusutils logfile. In case of problems you can check for yourself or ask on the forum with the log file as attachment. All logfiles are to be found in the directory utils/utilslog/ - which is automatically created if it does not exist - and they will have the name: yyMMddHHmmcumulusutils.log which sorts easily alphabetically. So that would be e.g. 2005271332cumulusutils.log. This gives the possibility to run CumulusUtils many times per day and if you find a problem later in one of the major runs at midnight, you still have that log. Logs will be kept for 2 days, giving you enough time to save the log you want to save. Errorlogging is governed by two inifile parameters: NormalMessageToConsole and TraceInfoLevel. See the page on cumulusutils.ini.
Development of CumulusUtils started in 9^th of August 2019 with an initial commit of the Top10 written in C. Development changed rapidly to C# with an initial commit of Top10 on November 19 2019 of version 0.7.0. The rest of the history can be read in the release notes.

NOTE: comments to this series of articles is welcome either by using the Talk feature of the Wiki for that page, direct edit of the article (request an account) or by contacting the author of CumulusUtils HansR on the forum or through PM.