Merge pull request #19 from wizzdev-pl/devel

KaaIoT cloud integration

.gitignore

@@ -1,13 +1,16 @@
 # terraform temps
 terraform/.tmp/**
 terraform/.terraform/*
+terraform/.terraform.lock.hcl
 
 # terraform bin
 terraform/terraform
 terraform/terraform.exe
 
-#JSON aws configuration file
+#JSON cloud configuration file
 MicroPython/src/aws_config.json
+MicroPython/src/kaa_config.json
+MicroPython/src/config.json
 
 # Python cache files
 *.pyc
@@ -16,8 +19,14 @@ venv/
 *.vscode/
 .env
 
+# Test
+kaa_test.py
+kaa_test_wifi.py
 
-Misc files
+# Ca
+ca.pem
+
+# Misc files
 *.info
 
 #Flash setup

KAA/README.md

@@ -0,0 +1,116 @@
+# Set up account and device on KaaIoT cloud platform
+The instruction walks you through the process of creating your own IoT device in just a few steps.
+
+## What is KaaIoT
+KaaIoT is a cloud service provider allowing for device management, data collection and visualization. You can create a powerful dashboard in a matter of seconds. It's free of charge with a limit of up to 5 devices.
+
+## Requirements
+
+### Python 3, PIP 
+Python can be downloaded from this [website](https://www.python.org/downloads) (in case of using [Anaconda environment](https://www.anaconda.com/products/individual), please skip this part and refer to "**Installation**" section). The Python version required for this project is: either 3.6 or 3.7 (preferably). Please follow installation instructions from their website. 
+After installation, you can check if it is installed correctly by typing the following commands in your terminal:
+
+* Linux
+```bash
+python3 --version
+pip3 --version
+```
+If python3 is not recognized, try "python"
+
+* Windows:
+```bash
+python --version
+pip --version
+```
+
+## Installation
+
+### 1. Create virtual environment:
+First, you need to create virtual environment (either with python venv module or anaconda-python):
+
+Note, that **"ENV_NAME"** is the name of the environment you’re creating.
+
+Enter main directory of the project (iot-starter):
+```bash
+cd iot-starter
+```
+
+* For anaconda (either in terminal - Linux or anaconda prompt - Windows):
+  ```
+  conda create --name ENV_NAME python=3.7 pip
+  ```
+
+* For venv:
+  * Linux:
+  ```
+  python3 -m venv ENV_NAME
+  ```
+
+  * Windows:
+  ```
+  python -m venv ENV_NAME
+  ```
+
+Next, you should activate it. This step is platform dependent:
+#### Windows
+* For anaconda:
+  ```
+  conda activate ENV_NAME
+  ```
+
+* For venv:
+  ```
+  ENV_NAME/Scripts/activate.bat
+  ```
+
+#### Linux/ Mac OS
+* For anaconda:
+  ```
+  conda activate ENV_NAME
+  ```
+
+* For venv:
+  ```
+  source ENV_NAME/bin/activate
+  ```
+
+### 2. Install requirements
+
+After you've created virtual environment, your current directory should be "iot-starter"
+
+``` 
+pip install pyserial cryptography click future pyelftools setuptools
+pip install -r KAA/requirements.txt
+```
+
+## Set up KaaIoT account
+
+If you are stuck or something will be unclear in next few steps, we recommend looking at official Kaa documentation about connecting your first device at this [link](https://docs.kaaiot.io/KAA/docs/v1.3.0/Tutorials/getting-started/connecting-your-first-device/).
+
+### 1. Create account
+
+First, you need to create an account on KaaIoT website: [kaaiot.com](https://www.kaaiot.com/).
+Click at the "Use Kaa for free" button at top right corner and follow standard procedure of registration.
+
+### 2. Create your first application and device endpoint
+
+After you log in into your new account (as a root user!), familiarize yourself with the UI and the options at the left side pane. 
+
+#### **Application version and autoextract:**
+
+ 1. Hover over the "Device management" option (first one) and select "Applications". In the right top corner click "Add application" and enter the name of your application and (optional) description.
+ 2. Click on the created application to expand it. On the right side look for "epts" and click on it. There you should see an option **"Autoextract"**. Make sure that the checkbox is checked.
+ 3. Go back to the application menu and expand the created application again. On the left side of the expanded window you will see “versions”. Click on the plus sign next to add a new version. You should see the "Name" field with a long sequence of random characters (like this one: c2t3ac6gul4q7qik0ol0-). There you should specify a version of your application. Let's go with something simple, add "v1" at the input field. **It is important for you to write this application version down as we will need it later - in this example it looks like: "c2t3ac6gul4q7qik0ol0-v1"**. You can add some optional display name and description for your convenience. After it is created, repeat step 2. but for the created version.
+
+#### **Device endpoint:**
+
+ 1. Hover over the "Device management" option (first one) and select "Devices". In the right top corner select the created application and then "Add device". Make sure you select a good application version and then supply an endpoint token. **IMPORTANT: Make sure to save this endpoint token as you cannot retrieve it later if you forget it.** After that, expand the "Additional metadata" field and click on "Add property". In the "Key" field supply "Label" and in the "Value" some unique identifier for this device (for example IoT-Starter). Click create, save endpoint token.
+
+ 2. Lastly, you need to create authentication credentials. For that go to "Device management" and click on "Credentials". On the right side look for a button with "Add basic credentials". On the left side of this button there are three smaller (symbol) buttons. Turn on the first two (plain MQTT and MQTT/TLS). After that all you need to do is create basic credentials, with username and password of your choice. **Remember to save both username and password as you will need it later.** Be careful as username is appended with your tenant id so it will look like: "username@b8e42266-8900-48d1-b99c-165f52j1d4f2"! (Password is not recoverable so make sure you save it for sure!)
+
+
+After all steps above you should have saved four things:
+ - application version
+ - device endpoint token
+ - username
+ - password

KAA/requirements.txt

@@ -0,0 +1 @@
+-r ./../MicroPython/requirements.txt

MicroPython/README.md

@@ -1,54 +1,69 @@
 ### Requirements
 - Created virtual environment
 - User added to dialup group
-- Configured AWS cloud
+- Configured chosen cloud
 
 
-### To develop in PyCharm:
-1. Activate previously created environment using venv or anaconda.
+## Activate virtual environment.
+
+```
+cd Micropython
+```
 
+This step is platform dependent:
+#### Windows
+* For anaconda:
     ```
-    cd Micropython
+    conda activate ENV_NAME
     ```
-    This step is platform dependent:
-    #### Windows
-    * For anaconda:
-        ```
-        conda activate ENV_NAME
-        ```
-
-    * For venv:
-        ```
-        ../terraform/scripts/ENV_NAME/Scripts/activate.bat
-        ```
-
-    #### Linux/ Mac OS
-    * For anaconda:
-        ```
-        conda activate ENV_NAME
-        ```
-
-    * For venv:
-        ```
-        source ../terraform/scripts/ENV_NAME/bin/activate
-        ```
-
-2. Open the project MicroPython with PyCharm and mark *src* and *ulib_mocks* directory as Sources Root in Pycharm.
-
-### AWS and terraform 
+
+* For venv:
+    ```
+    ../ENV_NAME/Scripts/activate.bat
+    ```
+
+#### Linux/ Mac OS
+* For anaconda:
+    ```
+    conda activate ENV_NAME
+    ```
+
+* For venv:
+    ```
+    source ../ENV_NAME/bin/activate
+    ```
+
+### To develop in PyCharm:
+
+Open the project MicroPython with PyCharm and mark *src* and *ulib_mocks* directory as Sources Root in Pycharm.
+
+## Cloud service provider: 
+
+### - KAA
+Make sure that your KAA cloud is configured. For more information please go to README in "KAA" directory [here](../KAA/README.md).
+
+By now, you should have four things:
+ - application version
+ - device endpoint token
+ - username
+ - password
+
+
+### - AWS
 Make sure that your AWS cloud is configured. For more information please go to 
 README in "terraform" directory [here](../terraform/README.md).
 
 If you already have configured AWS infrastructure, make sure that:
 - terraform exists either in ".terraform" directory or installed through the package manager
 - you have configured ssh connections with AWS (aws configure)
 
+
 ### Basic Setup of the ESP32
-To set up a new board or flash the old one. 
-Make sure that your AWS cloud is configured, and your computer has AWS credentials.
+To set up a new board or flash the old one. <br>
+Make sure that your cloud is configured and in case of using **AWS** make sure that your computer has AWS credentials.
 
 
-#### Flashing the board
+### Flashing the board
 Make sure that your board is connected to the computer and you have activated your virtual environment. 
 Check the port number - on Linux system, port can be checked through the simple script which will list all usb devices and their ports:
 
@@ -70,9 +85,10 @@ done
 After finding the correct port, execute:
 
 ```bash
-python scripts/upload_all.py -p <port>
+python scripts/upload_all.py -p <port> -c <cloud> -s <sensor>
 ```
-
+where \<cloud\> is your chosen cloud service provider (KAA or AWS).<br>
+where \<sensor\> is your currently used sensor (DHT11, DHT22 or BME280). Defaults to DHT22.<br>
 After flashing the board please reset it using button EN button.
 
 
@@ -85,14 +101,12 @@ For example:
 ```
 Wizzdev_IoT_8caab5b8c18c
 ```
-Network is open, so password will not be necessary. After successfull connection,
-please open your web browser and type in the Address Bar:
+If you are having difficulties connecting to the website, disable mobile data transfer and make sure that your phone does not reject the newly connected WiFi (as it may show it has no access to the internet).<br>
+Network is open, so password will not be necessary. After successfull connection, please open your web browser and type in the Address Bar:
 ```
 http://192.168.4.1/web_pages/setup.html
 ```
-Next, type your WiFi network credentials into SSID and Password fields and press
-"Submit" button. Remember that this network should have an internet connection. 
-Otherwise, data will not be sent to the AWS. 
+Next, type your WiFi network credentials into SSID and Password fields and press "Submit" button. Remember that this network should have an internet connection. Otherwise, data will not be sent to the cloud. <br>
 If you’ve lost connection after submitting, don’t worry - that is supposed to happen.
 
 ### Logs from the device
@@ -127,22 +141,4 @@ After installing connect to the device through:
 4. Open connection
 
 ### Mac 
-On Linux you can also use picocom
-
-### Checking measurement
-There are two ways to check measurements sent from the board. First is using AWS IoT core service, second is visualization page prepared by WizzDev.
-
-#### Using IoT Core
-Log in to your AWS account. Go to 'IoT Core' service. Next, choose "Test" and into "Subscription topic" type:
-```
-topic/data
-```
-Finally, click "Subscribe to topic". After some time you should see dataframes send by ESP32 board.
-
-#### Visualization page
-Visualization page url is generated by AWS during infrastructure build. So URL is connected with your AWS account. 
-You can find this URL in places listed below:
-- in file MicroPython/src/aws_config.json as **visualization_url**
-- in the "CloudFront" service on your AWS account under the **Domain Name** field
-
-
+On Mac you can also use picocom

MicroPython/requirements.txt

@@ -2,4 +2,4 @@ wheel
 esptool==2.8
 gitpython==3.1.17
 adafruit-ampy==1.0.5
-docopt>=0.6.2,<0.7
+docopt>=0.6.2,<0.7

MicroPython/scripts/cloud_credentials.py

@@ -0,0 +1,71 @@
+import argparse
+import logging
+import json
+from pathlib import Path
+
+
+KAA_CONFIG_SRC_PATH = 'src/kaa_config.json'
+
+
+def file_exists(path):
+    if Path(path).is_file():
+        return True
+    else:
+        return False
+
+
+def set_credentials():
+    """
+    Asks user for credentials for Kaa cloud similar to "awscli"
+    """
+    if file_exists(KAA_CONFIG_SRC_PATH):
+        with open(KAA_CONFIG_SRC_PATH, 'r', encoding='utf8') as infile:
+            config = json.load(infile)
+    else:
+        config = {}
+    print("Please provide kaa credentials:")
+    old_endpoint = config.get('kaa_endpoint', None)
+    old_app_version = config.get('kaa_app_version', None)
+    old_user = config.get('kaa_user', None)
+    old_password = config.get('kaa_password', None)
+
+    endpoint = input("Device endpoint token [{}]: ".format(old_endpoint))
+    app_version = input("App version [{}]: ".format(old_app_version))
+    user = input("User [{}]: ".format(old_user))
+    password = input("Password [{}]: ".format(old_password))
+    print()
+
+    # If values were not updated; leave the old ones
+    if endpoint:
+        config['kaa_endpoint'] = endpoint
+    if app_version:
+        config['kaa_app_version'] = app_version
+    if user:
+        config['kaa_user'] = user
+    if password:
+        config['kaa_password'] = password
+
+    with open(KAA_CONFIG_SRC_PATH, 'w', encoding='utf8') as outfile:
+        json.dump(config, outfile)
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser()
+
+    parser.add_argument(
+        '--set-credentials', action='store_true',
+        dest='creds', help="Set credentials needed for cloud service"
+    )
+
+    args = vars(parser.parse_args())
+    return args
+
+
+if __name__ == '__main__':
+    args = parse_arguments()
+
+    if args['creds']:
+        set_credentials()
+    else:
+        logging.info('Please run the script with "--set-credentials" flag!')
+