# Introduction to Plutonium

## Directory structure

Following structure is applied to this project. Some directories are minified in this view on purpose.

    .
    ├── chttpd.py
    ├── config
    │   └── plutonium.ini
    ├── config.py
    ├── doc ... (documentation in sphinx)
    ├── index.py
    ├── localdeploy.sh
    ├── modules
    │   ├── dynamic.py
    │   ├── status.py
    │   ├── temphumi.py
    │   ├── voltage.py
    │   └── weather.py
    ├── static
    │   ├── css
    │   │   ├── bootstrap.css
    │   │   └── dygraph.css ...
    │   ├── img
    │   │   ├── battery_0.png ...
    │   └── js
    │       ├── solar_graph.js
    │       ├── status_graph.js
    │       ├── temphum_graph.js
    │       └── weather_graph.js ...
    ├── templates
    │   ├── footer.html
    │   ├── header.html
    │   ├── landing_page.html
    │   ├── status_admin.html
    │   ├── temphumi_admin.html
    │   ├── top_menu.html
    │   ├── voltage_admin.html
    │   └── weather_admin.html
    └── TODO.txt

## CherryPy configuration (config.py)

Configuration is stored in a separate file statically, so each submodule can load the same configuration. This should be variables, that are project-wide.

### CherryPy configuration file (plutonium.ini)

Configuration file, .ini style. Option = value. File resides in ./config directory. It is read by confi.py and parsed into a dict(), available throughout the project.

    _server_protocol = https
    _server_name = bastart.spoton.cz
    _server_port = 80
    _server_bind_ip = 0.0.0.0
    _influx_host = localhost
    _influx_port = 8086
    _influx_user = pi
    _influx_pwd = password
    _influx_weather_db = weather_v2
    _influx_status_db = status
    _influx_voltage_db = voltage
    _influx_IoT_db = weather_v2

### Configuration classes and functions

Generic, system-wide variables and functions to be used in any / every module Global variables are defined with _variable_name schema, to be quickly identified in the project.

`config.``read_html`(filename, _STATIC_DIR)

  Read a html file

  Reads a file from a selected static directory - needs to be set as static in the cherrypy (chttpd.py).

  Args:
    `filename` str(), plain filename, without any path specification, without extension `_STATIC_DIR` str(), path relative to the project root, where chttpd.py resides
  Returns:
    str(), parsed html code from the read file, or a HTML formatted error if file cannot be read for any reason
  Exceptions:
    On file read fail, string with Exception text is returned

class `config.``serverConfiguration`

  Sets up Conf with appropriate values

  Creates an object that holds the configuration to the whole web server, is available throughout the project. This separates the .ini style config and the config.py script, that uses additional logic.

  `influx_connectors`()

    Set up client objects for InfluxDB

    All DB connector objects in one place. Callable from other modules

    Args:
      None
    Sets:
      `self.influx_weather_client`, `self.influx_voltage_client`, `self.influx_iot_client`, `self.influx_status_client`: Influx client connector objects
    Returns:
      N/A
  `read_config`(conf_filename)

    Reads configuration file

    Read and parse the configuration options into a dictionary Why not using configparser? No idea, subject to change. This method is called on class init.

    Args:
      `conf_filename`, str() file name without the .ini extension, residing in ./config directory
    Returns:

      dict(), On success

      bool(False), On failure

    Sets:
      `self.dict()` of name_value_pairs read from the config file

## CherryPy server (chttpd.py)

The server uses CherryPy module. For more information, please consult the Cherrypy documentation.

CHTTPD.py is also the executable, that can be launched as a standalone application by simply typing ./chttpd.py, or python3 chttpd.py

`chttpd.``main_server_loop`()

  Master http server - the main executable / daemon

  Contains basic server settings and how the sub-modules are called and mounted to their respective paths

  Args:
    None
  Sets:
    server_config: dict(), updates cherrypy.config conf: dict(), see Cherrypy docs for more cherrypy.config: dict(), see Cherrypy docs for more
  Returns:
    N/A
  Raises:
    Exception If server is unable to start

### Modules and web paths

Modules are located in the modules directory, hence the imports from a subdirectory

    from modules import voltage
    from modules import weather
    from modules import dynamic
    from modules import status
    from modules import temphumi

As can be seen, each class / module is mounted under a specific web path. This is the preferred way of future expansion modules.

    cherrypy.tree.mount(voltage.EnergyInfo(), "/", conf)
    cherrypy.tree.mount(voltage.EnergyInfo(), "/energy", conf)
    cherrypy.tree.mount(weather.WeatherInfo(), "/weather", conf)
    cherrypy.tree.mount(status.StatusInfo(), "/status", conf)
    cherrypy.tree.mount(dynamic.Expose(), "/data", conf)
    cherrypy.tree.mount(temphumi.PuerhInfo(), "/temphumi", conf)

## Index (index.py)

Reserved for future use. Currently not displayed, as the EnergyInfo() class is mounted under root(/) of the web, defined in chttpd.py

    cherrypy.tree.mount(voltage.EnergyInfo(), "/", conf)

class `index.``landingPage`

  Base Index constructor and expose function

## Indices and tables

- Index
- Module Index
- Search Page