The AlphaMon Configuration File System

The AlphaMon Platform includes a sub-system for creating and managing Configuration Files.  The following bullet points describe how this system works and how users can interact with it.

• Configuration Files (Config Files) are used by The AlphaMon Platform to restore critical system values after each power-down and restart and/or reboot of the processor.
• Config Files store information such as usernames, passwords, WiFi connection credentials, operating modes, upper limits for electrical currents, and so on.
• Config Files are stored in either or both of:
  1. A properly formatted microSD card (or SD for short), and/or
  2. A special area of the AlphaMon’s internal memory called SPIFFS (or SP for short).
• Both the SD and SP file storage areas are limited to short file names in the popular 8.3 byte format; for example, “AlphaMon.cfg”.
• In fact, AlphaMon.cfg is the default Config File name that AlphaMon will search for after each restart.  
• Although both the SD and SP storage areas can hold multiple files, each using the 8.3 file naming convention, the properties of the two areas are quite different, as follows:
  1. microSD cards are removable devices that can be read and written using a PC, laptop computer or similar device, allowing you to create and/or edit Config Files on remote devices.  
  2. Thus, the key advantage of SD storage is portability and ease of access to the data.  However, since the SD card may contain confidential information such as passwords, it is critical to ensure it is stored in a secured location; preferably under lock and key.
  3. The use of a microSD card is optional since AlphaMon will automatically create the config File in the SP storage area if an SD card can’t be found.
  4. Alternately, the SP storage is embedded in the micro controller’s silicon memory and there is no way to access the data in the Config File without running the AlphaMon app.
  5. Thus, the key advantage of Sp storage is security. 
• Facts about SD cards used with the AlphaMon Platform:
  1. The capacity of microSD cards is constantly growing, however the AlphaMon’s file management system can only access a maximum of 32 GBytes. Thus it is wise to not attempt to use a microSD card larger than this limit.
  2. Not all AlphaMon models have a socket that allows a microSD hard holder to be installed, however all AlphaMon devices have internal SP storage for Config Files.
  3. If your AlphaMon device has a socket for installing a microSD card it is critical to ensure the correct orientation of the card holder before plugging it in and powering it up. On most AlphaMon models the ground pin (labelled Gnd) is at the top of the board.  The SD card holder will have matching labels on the back (or front) face of the card.  
  4. Also, be sure to check the pin alignment; it is easy to install the card holder with the alignment out by one or more pins.  Unfortunately most microSD card holders don’t have a self-alignment mechanism or keyed socket.
  5. microSD cards are very complex devices and have their own communications, interfaces and processing power. The golden rule here is “not all microSD cards are made equal”.  Counterfeit devices, incorrect labelling, poor firmware implementations  are all common. Thus, if your SD card doesn’t work the first time, check and follow these remediation tasks:
     1. Install the microSD card in a holder (typically a USB style device) that allows it to be plugged into a PC or laptop.
     2. Ensure the PC or laptop can recognise the card. (If not, try reseating it a few times)..
     3. Check if the PC or laptop can open the root folder on the card. If not, the card may have to be reformatted.  New micoSD cards are normally shipped pre-formatted.
     4. If you’re using the formatting software on your PC or laptop to perform the formatting, select the “FAT32” option. Other formatting options won’t work on AlphaMon.
     5. If you’re still having issues with formatting the card you should try the “SD Card Formatter” published and distributed by the SD Association; that safe organisation responsible for developing the operating standards for all SD cards worldwide.  Your can find the app on their website, here: https://www.sdcard.org/downloads/formatter/
     6. Finally, if all of the above fails if you’re sure the SD card is properly seated in the AlphaMon’s microSD card holder, you should probably try another brand of microSD card and/or microSD card holder.
• If your AlphaMon has both SD and SP storage, sometimes it can be useful to know which Config File is being used by the application.  Thus, the following guide may help:
  1. On restart the AlphaMon Platform will look for an (optional) attached SD card.
  2. If the SD card is found and it contains an AlphaMon.cfg file then the SD card version is assumed to be the “current” version. 
  3. In this case, if there is also an AlphaMon.cfg file in the SP storage area it is first copied to the SD card and as AlphaMon.old.  
  4. This automatic export feature allows new AlphaMon.cfg files to be loaded from the SD card, perhaps containing the latest changes.
  5. The automatic export feature also allows a working Config File to be copied to other AlphaMon devices thus saving setup time. However, you’ll need a PC or laptop to rename the Config File back to AlphaMon.cfg.
  6. When the export process is complete AlphaMon proceeds to open and load the Config File contained in the SP storage area.’
  7. You can observe all the this setup activity via AlphaMon’s logging sub-system which writes all critical events to the USB port.
  8. To view the logging information you’ll need
     1. a USB-C cable plugged into the AlphaMon’s USB_C connector, 
     2. “terminal emulation” application software installed on your PC or laptop, such as the popular (and free) Putty app.  You can download and install Putty from www.putty,.org
     3. To configure your Putty or other terminal emulation software to:
        • 155200 bits per second (baud or BPS)
        • A byte length of 8, No Parity and 1 Stop Bit (8N1).
     4. Upon restarting Alphon you’ll see a stream of time and date stamped activity. Since the log stream can move very quickly you may have to configure Putty or other software to write the data stream to a disk file for later analysis.
     5. There are very good online instructions for the installation and configuration of Putty and most other terminal emulation software packages.  However the specifics are too detailed for inclusion here.
• AlphaMon Config Files are internally formatted as simple Json files and typically contain between 60 and 100 lines. See these tips for making changes to Config Files: Diving Deeper: Editing AlphaMon Configuration Files
• The following is an example of the content of a valid Config File, however even though the content isn’t the latest supported version it will still work because of AlphaMon’s self-correcting features. Missing Json parameters will be added, all parameters will be regrouped and reordered and the changes automatically saved, all whilst retaining existing valid values: