[WIP] Define Sherlock() class for better OOP

README.md

@@ -6,8 +6,8 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/Release-alpha-red.svg" />
-  <img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg">
+  <img src="https://img.shields.io/badge/Release-alpha-yellow.svg" />
+  <img src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-informational.svg">
 </p>
 
 <table align="center" style="background-color:rgba(0,0,0,0);">
@@ -37,59 +37,71 @@ This is the official repository for the **Hackability@Sherlock** project.
 The goal is to develop a **3D printed design object** which easily lets **visually impaired people** (but also normally sighted people) get a quick and informative **audio description of a small indoor space** - such as an hotel room, to get an understanding of where and which objects are present in the room.
 
 Sherlock will be composed of the following components:
-* an audio speaker.
-* an electronic circuit to "read" the user's input (through the pressing of buttons).
-* a Raspberry Pi to control everything.
-* a 3D printed casing, with buttons and Braille text.
+* an **audio speaker**.
+* an **electronic circuit** to "read" the user's input (through the pressing of **buttons**).
+* a **Raspberry Pi** to control everything.
+* a **3D printed casing**, with buttons and Braille text.
 
 We will try to make Sherlock as simple and yet configurable as possible, where users can just drag-and-drop their audio tracks to be reproduced and Sherlock will be able to reproduce them.
 
 Our vision is to create an object which integrates well into any environment and is able to make any person feel welcome and at home in any new indoor space.
 
 ## Installation
 
-Make sure your electronic circuit and PCB is built following the schema in `SherlockSketch.fzz`.
+0. Make sure your electronic circuit and PCB is built following the schema in `SherlockSketch.fzz`.
 
-Open a terminal window in your RaspberryPi (you can either connect through `SSH` or directly to the device).
+1. Open a terminal window in your RaspberryPi (you can either connect through `SSH` or directly to the device).
 
-Clone the repository into your preferred location:
+2. Clone the repository into your preferred location:
 ```
 cd /path/to/your/folder
 git clone https://github.com/Quellichenonsannofareuncazzo/Sherlock
 cd Sherlock
 ```
-**[Optional]** Create a virtual environment for the project:
+3. **[Optional]** Create a virtual environment for the project:
 ```
 python3 -m venv <your-venv-name>
 source <your-venv-name>/bin/activate 
 ```
-Install project dependencies:
+4. Install project dependencies:
 ```
-pip install -r requirements.txt
+pip3 install -r requirements.txt
 ```
 
 ## Usage
+1. Check and update the [`config/sherlock_parameters.yaml`](config/sherlock_parameters.yaml) configuration file with the actual pins used and with your preferred settings. More details on individual settings can be found in the `Sherlock` class [docstring](src/sherlock.py#L8).
 
-From the command line, run:
+2. From the command line, run:
 ```
-python3 main.py 
+python3 src/main.py 
 ```
 and enjoy the experience! 
 
+**N.B.**: at the moment, only `.mp3` audio files are supported. Please, do convert your audio files to the supported file formats.
+
 ## To-do List
 
 Below, a non-comprehensive list of stuff we should do in the future:
-* Update `README.md` with the exact RaspberryPi model used for prototyping and testing (including Ubuntu distro, Python version, etc.) for reproducibility purposes.
-* Create a file with detailed technical specifications of the electronic components (resistors, LEDs, etc.).
-* Clean and update `requirements.txt` and check all dependencies (eventually try to see if we can work with the latest releases to get better long-term support).
-* Use conda venvs instead of python venv, so that we can also control the Python version
-* Add the outer case 3D CAD model file to the repository.
-* Add images of Sherlock's final prototype, and possibly of videos of it working. Also, add other images to use in the `README.md` file (e.g., ~~Sherlock and Hackability logos~~, electronic circuit, 3D CAD model, etc.).
-* Add shields for release, license, etc.
+* **[VERY HIGH]** `set_pos` only sets position with respect to `get_pos` (which does not update when calling `set_pos`). Therefore, need to define an attribute in the Sherlock class with the time from playback start (else, fast-forward/fast-backward won't work).
+
+* **[HIGH]** Implement fast-backward.
+* **[HIGH]** Test fast-for/backward functions when end/start of track is reached.
+
+* **[MEDIUM]** Update `README.md` with the exact RaspberryPi model used for prototyping and testing (including Ubuntu distro, Python version, etc.) for reproducibility purposes.
+* **[MEDIUM]** Clean and update `requirements.txt` and check all dependencies (eventually try to see if we can work with the latest releases to get better long-term support).
+* **[MEDIUM]** Add the outer case 3D CAD model file to the repository.
+
+* **[LOW]** Create a file with detailed technical specifications of the electronic components (resistors, LEDs, etc.).
+* **[LOW]** Use conda venvs instead of python venv, so that we can also control the Python version.
+* **[LOW]** Add images of Sherlock's final prototype, and possibly of videos of it working. Also, add other images to use in the `README.md` file (e.g., ~~Sherlock and Hackability logos~~, electronic circuit, 3D CAD model, etc.).
+
+* **[VERY LOW]** Add shields for release, license, etc.
 
 Use GH Issues to open MRs/PRs for new improvements and adding functionalities.
 
-## Acknowledgements & Contacts
+Task priorities are in brackets.
+
+## Acknowledgements
 
 The Sherlock project was realized by [Hackability@Milano](http://www.hackability.it/hackabilitymilano/), in partnership with [Fondazione G. Brodolini](https://www.fondazionebrodolini.it/) and [Associazione Nazionale Subvedenti](https://www.subvedenti.it/), whose contributions were essential for the brainstorming and development of Sherlock. 
 
@@ -100,6 +112,7 @@ The project was initially ideated in the context of the [EU's ECOS4IN project](h
 
 Sherlock is a byproduct of the **ECOS4IN Workshop** organized by Fondazione G. Brodolini with makers from Hackability@Milano, and inclusion stakeholders from Associazione Nazionale Subvedenti. 
 
+## Contacts
 If you have any questions, want to contribute, or want more information, feel free to reach out to us.
 * **Hackability@Milano**, [milano@hackability.it](mailto:milano@hackability.it)
 * Teo Bistoni, [@TeoBistoni](https://github.com/TeoBistoni)
@@ -116,4 +129,4 @@ The Sherlock project is licensed under the [Creative Commons Attribution-NonComm
 [![CC BY-NC-SA 4.0][cc-by-nc-sa-image]][cc-by-nc-sa]
 
 [cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0/
-[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png
+[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png

config/sherlock_parameters.yaml

@@ -0,0 +1,12 @@
+TRACKS_DIR: './tracks'
+FW_PIN: 3
+BW_PIN: 5 
+PLAY_PIN: 11 
+OUT_PIN: 13
+BOUNCE: 200 # [milliseconds]
+SKIP_TIME: 10 # [seconds]
+LONG_PRESS_TIME: 2 # [seconds]
+CURRENT_IDX: 0 
+PLAY_STATE: False
+RESTART_TIME: 2 # [seconds]
+SUPPORTED_FORMATS: ['mp3']

requirements.txt

@@ -56,6 +56,7 @@ pyinotify==0.9.6
 PyJWT==1.7.0
 pyOpenSSL==19.0.0
 pyserial==3.4
+pyyaml
 pyxdg==0.25
 rainbowhat==0.1.0
 requests==2.21.0

src/main.py

@@ -0,0 +1,75 @@
+import os
+import yaml
+
+from sherlock import Sherlock
+
+def welcome_sherlock():
+    '''Prints welcome and instructions for usage.'''
+    # Print instructions
+    print('#'*10)
+    print('WELCOME TO SHERLOCK! :)')
+    print('#'*10)
+    print('\n')
+    print('#'*5)
+    print('INSTRUCTIONS')
+    print('#'*5)
+    print('1. Press the right button (NEXT) to skip to the next track.')
+    print('2. Press the central button (PLAY/PAUSE) to play/pause the track.')
+    print('3. Press the left button (BACK) to go back to the previous track.')
+    print('4. Long press the right button (NEXT) to fast-forward the current track.')
+    print('5. Long press the left button (BACK) to fast-backward the current track.')
+    print('\n')
+    print('Have fun!')
+
+def goodbye_sherlock():
+    '''Prints closing message for KeyboardInterrupt exception.'''
+    # Print goodbye
+    print('#'*10)
+    print('GOODBYE! COME BACK SOON! :)')
+    print('#'*10)
+
+def read_yaml(config_path='./config/sherlock_parameters.yaml'):
+    '''
+    Reads a .yaml file from the specified path. Returns a dict of parameters.
+
+    Args:
+        config_path (str)   : path to .yaml config file
+
+    Returns:
+        params_dict (dict)  : dict containing the parameters in config file
+    '''
+    # Load parameters file
+    with open(config_path, 'r') as param_file:
+        params_dict = yaml.load(param_file, Loader=yaml.FullLoader)
+
+    return params_dict
+
+def main():
+    '''Starts main loop by initializing the Sherlock device.'''
+    # Load configuration parameters
+    sherlock_params_dict = read_yaml()
+
+    # Initialize the device
+    sherlock = Sherlock(**sherlock_params_dict)
+
+    # Continue listening to events
+    while True:
+        pass    
+
+if __name__=='__main__':
+    '''
+    Wraps main loop in a try-except exception handling to catch 
+    KeyboardInterrupt as quit event.
+    '''
+    try:    
+        # Welcome message and instructions
+        welcome_sherlock()
+        # Start main loop
+        main()
+    # Catch CTRL+C command for quitting
+    except KeyboardInterrupt:
+        # Say goodbye
+        goodbye_sherlock()
+    # Deal elegantly with other errors and quit
+    except Exception as ex:
+        print('Encountered the following error: ', ex)