uun_iot.modules package

Submodules

uun_iot.modules.BaseHealthCheck module

class uun_iot.modules.BaseHealthCheck.BaseHealthCheck(gconfig, on_stop=True, on_update=True)

Bases: uun_iot.modules.Module.Module

Base class for creating runtime consistency checks and debug diagnostics.

HealthCheck modules can log incoming events and act correspondingly, ie. a HealthCheck module can restart application if the app is not working correctly and log more debugging information for further analysis.

This can be useful for detecting anomalous cases when the app is not working correctly due to an unknown bug, typically when the bug occurs at weird edge cases in long running apps. At the same time, it allows to recover from the case (by restarting) and to collect diagnostic info.

HealthCheck can monitor multiple modules at the same time. This is done using @on("tick", "moduleId") timers.

The monitored modules need to explicitly send information to the HealthCheck module as this cannot always be automatized.

Event informations are submitted by monitored modules via notify() method in a form of uun_iot.diagnostic.GeneralDiagnosticEvents.

BaseHealthCheck only provides infrastructure for storing these events and it is upto app-specific HealthCheck to implement neccessary logic for determining malfunctioning app states. Although, some helper functions for usual cases are already present in BaseHealthCheck (_act_if_data_not_sent()).

BaseHealthCheck can register basic @on methods automatically. This is useful, as most of derived HealthCheck modules will need save_all_diagnostics registered as @on(stop) and _init_module_config registered as @on(update) for updating module-specific leeways etc.

Sample gconfig:

 {
    "moduleTimers": {
        "healthCheck": {
            "weatherConditions": 300
        }
    }

    "healthCheck": {
        "diagnosticPath": "diagnostics/",
        "modules": {
            "weatherConditions": {
                "leeway": 120
            }
        }
    }
}

Leeways should be sufficiently large (larger than watched module’s timers), so that the module can do its function well. Only module-level configuration is dynamically updateable: leeways,

Parameters:

  • gconfig (dict) – gateway configuration

  • on_stop (bool) – default True, assign @on("stop") decorator to _save_all_diagnostics()

  • on_update (bool) – default True, assign @on(“update”) decorator to _init_module_config()

notifier(mid)

Return a notify() method with prefilled mid argument.

Parameters:

mid (str) – module ID

notify(mid, event, *args, **kwargs)

Notify HealthCheck about watched modules’ events.

Optionally, add more custom data about the event in form of additional *args or **kwargs.

Parameters:

  • mid (str) – watched module ID

  • event (uun_iot.diagnostic.GeneralDiagnosticEvent) – GeneralDiagnosticEvent representing what action was done

  • *args – other positional arguments for logging purposes

  • **kwargs – other keyword arguments for logging purposes

save_all_diagnostics()

Stop all diagnostics and save them to files.

save_diagnostic(mid)

Stop logging incoming events for mid and save them to file.

start_diagnostic(mid)

Start logging incoming events for module mid.

uun_iot.modules.Heartbeat module

class uun_iot.modules.Heartbeat.Heartbeat(uucmd)

Bases: uun_iot.typing.IModule

Ping server in short periods to let server know if the gateway is online and send a little info about the gateway.

Parameters:

uucmd (Callable[[Dict], requests.models.Response]) – function (dto_in) -> requests.Response, the function takes an argument with data to be sent to the heartbeat uuCmd endpoint. It returns the reponse formed using requests.Response.

id: str = 'heartbeat'
on_tick()

Determine online status and send a little information about gateway to uuApp.

The online status is determined using self._uucmd uuCmd. The information sent includes

  • boot timestamp (in ISO timestamp)

  • CPU usage in percent

  • RAM usage in percent

Executed on each timer tick.

uun_iot.modules.Module module

class uun_iot.modules.Module.ConfigScopeEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: enum.Enum

Enumeration for configuration scopes.

GATEWAY = 1

Use the root gateway key for the module configuration.

SELF = 2

Use the gateway.moduleId key for the module configuration.

class uun_iot.modules.Module.Module(config={}, uucmd=None)

Bases: uun_iot.typing.IModule, abc.ABC

Provides utility functions for modules.

Class Module implements interface uun_iot.typing.IModule for derived classes automatically. The id attribute is derived from the class name using uun_iot.utils.module_id_from_str(). If the class already has the id attribute, keep it.

The derived classes must call the Module’s init function using super(). Example:

from uun_iot import Module
class TestModule(Module):
    def __init__(self, config, uucmd):
        super().__init__(config=config, uucmd=uucmd)
        self.attribute1 = "value1"

The utility functions include:

  • configuration management

  • storage management

  • backup and restore of storage to filesystem (useful for power failures)

  • automation for sending storage to uuApp

  • handling of failed send storage actions (useful for unstable internet connection)

Configuration management:

Access configuration in easy way as self._c("key/subkey/subsubkey") instead of cumbersome self._config["key"]["subkey"]["subsubkey"] and more. See configuration manager _config_manager() or its alias _c().

Storage management:

An instanced thread-safe Storage is available as _storage. The class provides backup and restore to JSON files and limiting the storage in number of its entries. If enabled, oldest entries will be removed for the sake of newer ones.

If the derived class does not have the _config attribute, set it to the constructor argument config.

Parameters:

  • uucmd (Callable[[Any], List]) – function(storage)->failed_send_data to send data to uuApp server

  • config (dict) – gateway configuration

id: str = None

is set in __init__() dynamically according to derived class

Module contents

Initialize modules.

uun_iot.modules.init(config, uuclient)
Parameters: