kiwrious 0.0.7
Package for interacting with Kiwrious sensors
Requires Python: >=3.7

# Fellas in COMPSCI 399
Kiwrious Python Sensor Library - An open-source Python library for programming with real-time sensor data. 

## Background  
Input to programs created using Python typically happen using keyboard and mouse. The ability to incorporate real-time
environmental data measured through sensors as input could open doors to new programming experiences.

With this in mind, we have developed a toolkit consisting of six plug-and-play Kiwrious USB sensors that measure various physical phenomena such as humidity, temperature, conductance, air quality, light and heart rate.

You can read our final report [here](link_that_shit_here)

## Project Description
The goal of this project is to develop a python library that services all sensor communications to allow users to easily program with their data.

Basic functions that the library should handle include establishing stable sensor connectivity, decoding live sensor data and
providing appropriate methods for working with this data.

Users can then use this sensor data in tasks like visualizations (e.g. Matplotlib), creating data models for investigations (e.g. sci-kit) or developing games that react to changes in the environment (e.g. pygame).

## Installation Guide
This library can be installed through pip using a terminal using the following command:

```
$ python -m pip install kiwrious
```
Our library can be accessed on the pypip website [here](https://pypi.org/project/kiwrious/)

## Available Resources

Below are the available methods included in this library as well as a brief description of their function:

```python
get_raw_data(sensor_type)
```  

This method takes a specified sensor as an input and returns a list of the raw packet data in the form of a byte string.

```python
get_connected_sensors()
```  

This method returns a list of all Kiwrious sensors that are connected to your computer.

```python
get_sensor_reading(sensor_type)
```  

This method takes in a specfied sensor as an input and returns the processed data reading. Each sensor will return two different readings, which are specified in the returned list.  
If no sensor is specified, it will automatically detect the connected sensor(s) and return the data readings.

### Callback Methods
This library also includes callback methods, which allows the user to specify a defined method to run once the callback's condition has been met. A brief description and their functions are described below:  

```python
on_sensor_connection(callback_method, sensor_type, timeout, close_on_completion, *args)
```  

This callback method enables the user to run their self-defined function once a sensor is connected to the computer. The arguments of this callback method are defined as: 

callback_method: the user defined method to run  
sensor_type: the sensor that the callback looks for to run callback_method once it is connected. If no sensor_type is specified, callback_method will run once any sensor is connected  
timeout: the amount of time the service waits for a sensor to be connected before exiting the program. By default, this is set to 0, meaning it will never automatically exit  
close_on_completion: a boolean value which is set to False by default. If set to True, the service will stop once callback_method has completed  
args: these are the arguments that will be passed to callback_method

```python
on_sensor_disconnect(callback_method, sensor_type, timeout, close_on_completion, *args)
```  

This callback method enables the user to run their self-defined function once a sensor has been disconnected from the computer. The arguments for this method are the same as the above.

## Basic Usage
Once the Kiwrious library has been installed, it is quite easy to start reading data from the sensors. You simply import the library into a python file and do the following:

```python
from kiwrious.service import KiwriousService

my_service = KiwriousService()
my_service.start_service()

print(my_service.get_sensor_reading(my_service.HUMIDITY))

my_service.stop_service
```  
The six sensors can be used through the following:
```
Humidity: my_service.HUMIDITY
Temperature: my_service.TEMPERATURE
Air quality: my_service.AIR_QUALITY
UV: my_service.UV
Conductivity: my_service.CONDUCTIVITY
Heartrate: my_service.HEART_RATE

```
## Demo Programs
We have two demos that show the basic usage of our library:
 - live_plot_demo: This demo provides a live plot of the sensor data. It supports multiple sensors at the same time and can be run simply by plugging in a sensor(s) and running the program. 
 
 _Note: This program requires the Python library matplotlib to be run. You can download this by typing ''' $ pip install matplotlib ''' into a terminal._
 - rocket_demo: This demo is a simple demonstration of using a sensor in a game. This game uses the air quality sensor, and by blowing into it, the rocket will accelerate and move up the screen. Simply plug in the air quality sensor and run the program to play.
 
 _Note: This program requires the Python library pygame to be run. You can download this by typing ''' $ pip install pygame ''' into a terminal._
 
You can access some demo programs [here](https://github.com/uoa-compsci399-s2-2022/fellas_in_compsci_399/tree/example-demos/example_demos)

## Technologies Used
The technologies we used are listed below:
 - pyserial: We used this to read the byte stream taken from each individual sensor
 - Python: We implemented our library in Python
 - Github: We used Github during development of our library. Through the use of branching, we were able to implement each aspect of our project individually

## Project Management 
We used Jira for project management throughout the semester. You can access this [here](https://team-31-399.atlassian.net/jira/software/projects/T3/boards/2/roadmap)

## Future Plans 
- Improvement of the decoding algorithm for the heartrate sensor. 

## Acknowledgements
We would like to thank the COMPSCI 399 teaching team (Asma & Anna) as well as our client (Hussel) for assisting us throughout the semester. They were very helpful through the whole development process!

## Group Members
 - David Giles (Group leader)
 - Benjamin Wong
 - Matthew Lee
 - Matthew Fegan
 - Timothy Sanvictores 
 - Sam Adams