Pyrrha rules and decision engine

This repository contains the Pyrrha solution application for determining thresholds in toxin exposure measured by the sensor device and sent to the cloud from the Samsung smartphone carried by the firefighters.

This service wakes up every minute and calculates time-weighted average exposures for all firefighters and compares them to the configured limits.

Contents

• Contents
• Background
• Prerequisites
• Running MariaDB
• Run locally with Python
• Run locally with Docker
• Run on Kubernetes
• Troubleshooting
• Built with
• Contributing
• License

Background

In this repository you'll find a solution that goes beyond just reading the real-time parts-per-million readings that come from the sensor. The code here assesses the cumulative effect of exposure by calculates short-term exposure and time-weighted averages over 10 minute, 30 minute, 60 minute, 4 hour, and 8 hours.

The goals for this project are to:

• Present gas exposure information to firefighters in a way that is helpful and actionable
• Use standard metrics for gas exposure that align with regulations and standards
• Understand expectations across several regions (EU, US, Australia, etc)

Understanding the terminology

An excellent top-level summary is available from OSHA Environmental Compliance Systems.

That resource summarizes all the different standards into 3 main concepts. Generally speaking, PEL/TLV/REL have three subcategories:

1. Time-weighted average (TWA) - for the whole workday.
2. Ceiling value - should never be exceed at any time.
3. Short term exposure limit (STEL) - the 10 or 15 min TWA concentration (not 8 hours).

Other useful information

• Regulatory organizations and federal agencies establish safety and health laws and recommendations. This includes federal laws established by the Occupational Safety and Health Administration (OSHA) and NIOSH recommendations, which are called recommended exposure levels (RELs). Nongovernmental organizations, such as the American Conference of Governmental Industrial Hygienists (ACGIH) also publish threshold limit values (TLVs). Together these are called occupational exposure levels (OELs) designed to protect the health and safety of workers.
• Wildland Firefighter Smoke Exposure
• NIH glossary that is helpful for understanding how an PEL relates to a REL or a STEL or a TWA. In the context of submarines, but still covers all the standards and what they mean.
• ACGIH and NIOSH make recommendations/guidelines. OSHA makes law: Permissible Exposure Limits – Annotated Tables
• OSHA carbon monoxide limits
• Carbon monoxide limits for Spain, in Spanish from Joan Herrera
• Australian limits
• AEGL / IDLH (Immediately Dangerous to Life or Health Concentrations (IDLH)) from the CDC.
• Honeywell personal gas monitor user manual gives a sense of how people are used to thinking about these limits

Prerequisites

1. Docker
2. Docker-Compose
3. Kubectl
4. Helm
5. Skaffold
6. IBM CLI

Running MariaDB

MariaDB is a prerequisite for running the rules and decision engine service. Follow the instructions in Pyrrha-Database repository to build and run MariaDB locally using Docker. The following steps assume you have MariaDB running locally as a standalone service or as a docker container.

Run locally with Python

1. Copy src/.env.example to src/.env and fill out with MariaDB credentials that you set up in the previous step.

   MARIADB_HOST=localhost
   MARIADB_PORT=3306
   MARIADB_USERNAME=root
   MARIADB_PASSWORD=${MDB_PASSWORD}
   MARIADB_DB=pyrrha
   

2. Create python virtual environment

   python3 -m venv python3
   

3. Activate virtual environment

   source python3/bin/activate
   

4. Install the dependencies

   pip install -r requirements.txt
   

5. Run the application

   python src/core_decision_flask_app.py 8080
   
   

You can run this solution locally in docker as follows

1. Set up environment variables in the src/.env file

2. Install MariaDB locally

   1. Pull MariaDB from DockerHub

      docker pull mariadb 

   2. Run the image

      docker run --rm -p 3306:3306 --name pyrrha-mariadb -e MARIADB_ALLOW_EMPTY_ROOT_PASSWORD=true -d mariadb

   3. Test the image - TBD

3. Create Python virtual environment

   python3 -m venv python3

4. Activate virtual environment

   source python3/bin/activate

5. Run the application

   python src/core_decision_flask_app.py 8080

    starting application
    * Serving Flask app "core_decision_flask_app" (lazy loading)
    * Environment: production
    WARNING: Do not use the development server in a production environment.
    Use a production WSGI server instead.
    * Debug mode: off
       Use a production WSGI server instead.
    * Debug mode: off
    INFO:werkzeug: * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)
   

6. You should see the following output

   starting application
   * Serving Flask app "core_decision_flask_app" (lazy loading)
   * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
   * Debug mode: off
   * Running on <http://0.0.0.0:8080/> (Press CTRL+C to quit)

Run locally with Docker

If you are running MariaDB as a docker container, we recommend you use the build file located in the Pyrrha-Deployment-Configurations repository to start the rules and decision engine service. Run the following after configuring the services as explained in the instructions.

docker-compose up --build pyrrha-rulesdecision

You can stop the services with:

docker-compose stop pyrrha-rulesdecision

If you want to run build and run this image as a docker container and not use docker-compose, you can follow these steps:

1. Build the image

   docker build . -t rulesdecision
   

2. Run the image using the following command. Notice we are passing in the src/.env file as environment variable. This will not work if MariaDB is running in a docker image as localhost:3306 will not resolve to the right image.

   docker run -p8080:8080 --env-file src/.env -t rulesdecision
   

3. You should see the application logs

4. Build the image

   docker build . -t rulesdecision

5. Run the image

   docker run -p8080:8080 -t rulesdecision

6. You should see the application logs

   starting application
   * Serving Flask app "core_decision_flask_app" (lazy loading)
   * Environment: production
   WARNING: Do not use the development server in a production environment.
   Use a production WSGI server instead.
   * Debug mode: off
   * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit)

You can also use docker-compose to run all the services by using the build file located in the Pyrrha-Deployment-Configurations repository.

Run on Kubernetes

You can run this application on Kubernetes using the helm charts provided in Pyrrha-Deployment-Configurations repository. The skaffold.yaml file provided here let's you quickly run the application on the cluster by using Skaffold. There are two profiles provided. To run the solution on the test namespace use: skaffold dev -p test

Troubleshooting

1. Database does not connect

   1. ensure .env file has the correct values for database connection

2. Change the db password

Built with

• Docker
• MariaDB
• Flask
• IBM Kubernetes Service

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting Pyrrha pull requests.

License

This project is licensed under the Apache 2 License - see the LICENSE file for details.