Skip to content
This repository has been archived by the owner on Apr 7, 2024. It is now read-only.

Latest commit

 

History

History
executable file
·
85 lines (51 loc) · 5.23 KB

SETTINGS_SYSTEM.md

File metadata and controls

executable file
·
85 lines (51 loc) · 5.23 KB
Raw

Important

⚠ This is a public archive and the active project has been renamed to NetAlertX and moved: jokob.sk/NetAlertX

  • To differentiate from the upstream stale project
  • To differentiate from other active forks
  • To indicate this is not a Raspberry Pi-specific tool anymore

⚙ Setting system

This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project.

If you are a user of the app, settings have a detailed description in the Settings section of the app. Open an issue if you'd like to clarify any of the settings.

🛢 Data storage

The source of truth for user-defined values is the pialert.conf file. Editing the file makes the App overwrite values in the Settings database table and in the table_settings.json file.

Settings database table

The Settings database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the pialert.conf file. A high-level overview on the database structure can be found in the database documentation.

table_settings.json

This is the API endpoint that reflects the state of the Settings database table. Settings can be accessed with the:

  • getSetting(key) JavaScript method

The json file is also cached on the client-side local storage of the browser.

pialert.conf

Note

This is the source of truth for settings. User-defined values in this files always override default values specified in the Plugin definition.

The App generates two pialert.conf entries for every setting (Since version 23.8+). One entry is the setting value, the second is the __metadata associated with the setting. This __metadata entry contains the full setting definition in JSON format. Currently unused, but intended to be used in future to extend the Settings system.

Plugin settings

Note

This is the preferred way adding settings going forward. I'll be likely migrating all app settings into plugin-based settings.

Plugin settings are loaded dynamically from the config.json of individual plugins. If a setting isn't defined in the pialert.conf file, it is initialized via the default_value property of a setting from the config.json file. Check the Plugins documentation, section ⚙ Setting object structure for details on the structure of the setting.

Screen 1

Settings Process flow

The process flow is mostly managed by the initialise.py file.

The script is responsible for reading user-defined values from a configuration file (pialert.conf), initializing settings, and importing them into a database. It also handles plugins and their configurations.

Here's a high-level description of the code:

  1. Function Definitions:

    • ccd: This function is used to handle user-defined settings and configurations. It takes several parameters related to the setting's name, default value, input type, options, group, and more. It saves the settings and their metadata in different lists (conf.mySettingsSQLsafe and conf.mySettings).

    • importConfigs: This function is the main entry point of the script. It imports user settings from a configuration file, processes them, and saves them to the database.

    • read_config_file: This function reads the configuration file (pialert.conf) and returns a dictionary containing the key-value pairs from the file.

  2. Importing Configuration and Initializing Settings:

    • The importConfigs function starts by checking the modification time of the configuration file to determine if it needs to be re-imported. If the file has not been modified since the last import, the function skips the import process.

    • The function reads the configuration file using the read_config_file function, which returns a dictionary of settings.

    • The script then initializes various user-defined settings using the ccd function, based on the values read from the configuration file. These settings are categorized into groups such as "General," "Email," "Webhooks," "Apprise," and more.

  3. Plugin Handling:

    • The script loads and handles plugins dynamically. It retrieves plugin configurations and iterates through each plugin.
    • For each plugin, it extracts the prefix and settings related to that plugin and processes them similarly to other user-defined settings.
    • It also handles scheduling for plugins with specific RUN_SCHD settings.

  4. Saving Settings to the Database:

    • The script clears the existing settings in the database and inserts the updated settings into the database using SQL queries.

  5. Updating the API and Performing Cleanup:

    • After importing the configurations, the script updates the API to reflect the changes in the settings.
    • It saves the current timestamp to determine the next import time.
    • Finally, it logs the successful import of the new configuration.