Added esp32 documentation

blynkkk · antohaUa · Mar 4, 2019 · Feb 11, 2019 · Feb 12, 2019 · Feb 13, 2019
commit ee5c34acfadfdcfd608ef41eea755f9d77dd8472
diff --git a/README.md b/README.md
@@ -2,11 +2,11 @@
 Blynk Python/Micropython Library
 
 ## What is Blynk?
-Blynk provides **iOS** and **Android** apps to control any hardware **over the Internet** or **directly using Bluetooth**.
+**[Blynk][blynk-io]** provides **iOS** and **Android** apps to control any hardware **over the Internet** or **directly using Bluetooth**.
 You can easily build graphic interfaces for all your projects by simply dragging and dropping widgets, **right on your smartphone**.
 Blynk is **the most popular IoT platform** used by design studios, makers, educators, and equipment vendors all over the world.
 
-`![Blynk Banner][blynk-banner]
+![Blynk Banner][blynk-banner]
 
 ## Download
 
@@ -18,7 +18,7 @@ Optionally: **[Blynk Server][blynk-server]**. Public Blynk Cloud is free for any
 
 ![Blynk Architecture][blynk-architecture]
 
-## [Installation][blynk-io] 
+## Installation 
 
 #### Installation via Python pip
     sudo pip install blynklib   
@@ -37,13 +37,14 @@ You can run unit tests using the command:
     python setup.py test
 
 ## Features
-Library allows to communicate with public or custom [Blynk Server][blynk-server]
+Library allows to communicate with public or custom [Blynk Server][blynk-server]. 
+Supports Python2/Python3/Micropython. HW support of RaspberryPi/Esp32
 
 ##### List of available operations:
  - connect/disconnect events subscribe
- - read/write virtual pins events subscribe
- - virtual pin write
- - virtual pin sync
+ - read/write [virtual pins][blynk-vpins] events subscribe
 - [virtual pin][blynk-vpins] write
+ - [virtual pin][blynk-vpins] sync
  - internal app notifications
  - email notifications
  - set widget property
@@ -62,15 +63,47 @@ import blynklib
 BLYNK_AUTH = '<YourAuthToken>'
 blynk = blynklib.Blynk(BLYNK_AUTH)
 
+# register handler for succesful device connect to server
 @blynk.handle_event("connect")
 def connect_handler():
     print('Connect to Blynk server successful!')
-
+
+    # user code goes here
+    # ...
+    # For example power on/re-init sensors etc
+
+# register handler for virtual pin V11 reading
+# for example when some widget gets data from virtual pin once per 10 seconds    
+@blynk.handle_event('read V11')
+def read_virtual_pin_handler(pin):
+
+    # user code goes here
+    # ...
+    # For example calculate, get sensor values etc
+
+    # update value on server 
+    blynk.virtual_write(pin, <USER_CALCULATED_VALUE>)
+    if <USER_CALCULATED_VALUE>  >= <USER_DEFINED_CRITICAL_VALUE>
+        blynk.set_property(pin, 'color', '#FF0000')
+        blynk.notify('Warning critical value')
+        blynk.email(<Your e-mail>, 'Device alarm', 'Critical value!')
+
+# register handler for when device was disconnected from server
+@blynk.handle_event("disconnect")
+def connect_handler():
+    print('Device was disconnected')
+
+    # user code goes here
+    # ...
+    # For example power off sensors, try to recconect etc
+
+
+# main loop that starts program and handles registered events
 while True:
     blynk.run()
 ```
 
-Examine more Blynk python library **[examples][blynk-py-examples]** to be familiar with basic features usage.
+Examine more **[examples][blynk-py-examples]** to be familiar with basic features usage.
 
 
 ### License
@@ -87,4 +120,4 @@ This project is released under The MIT License (MIT)
   [blynk-py-examples]: https://github.com/blynkkk/lib-python/blob/master/examples
   [blynk-app-android]: https://play.google.com/store/apps/details?id=cc.blynk
   [blynk-app-ios]: https://itunes.apple.com/us/app/blynk-control-arduino-raspberry/id808760481?ls=1&mt=8
-
+  [blynk-vpins]: http://help.blynk.cc/getting-started-library-auth-token-code-examples/blynk-basics/what-is-virtual-pins
diff --git a/examples/esp32/00_HOWTO.txt b/examples/esp32/00_HOWTO.txt
diff --git a/examples/esp32/README.md b/examples/esp32/README.md
@@ -0,0 +1,108 @@
+# [ESP32 Micropython][esp32]
+
+![esp32][esp32-banner]
+## Board preparation
+
+ - download latest micropython [firmware][micropython-download] for your board
+ - on your host system install python3 
+ - install [esptool][micropython-esptool], [rshell][micropython-rshell], [ampy][micropython-ampy] on your host to communicate with esp32 board
+    ```bash
+    # Example on Linux 
+    sudo pip3 install esptool
+    sudo pip3 install rshell
+    sudo pip3 install adafruit-ampy
+    ```
+
+ - connect board via USB. Run command: 
+   ```bash
+    dmesg | grep tty
+   ```
+    that will help to find ttyUSB connection port.This port will be used later for all communication operations
+
+ - check board flash status. (In this example and below we assume that port=ttyUSB0)
+   ```bash
+    esptool.py --port /dev/ttyUSB0 flash_id
+   ```
+
+ - erase board flash before new firmware uploading
+   ```bash
+    esptool.py --chip esp32 --port /dev/ttyUSB0 erase_flash
+   ```
+
+ - burn new firmware
+   ```bash
+    esptool.py --chip esp32 --port /dev/ttyUSB0 write_flash -z 0x1000 <your esp32 firmware .bin>
+   ```
+
+## Board CLI
+
+ - For board CLI access [rshell][micropython-rshell] can be used:
+   ```bash
+    rshell --buffer-size=30 -p /dev/ttyUSB0
+   ```
+   after board prompt appears ">" you will have access to some board commands:
+   ```text
+   args      cat       connect   echo      exit      filetype  ls        repl      rsync
+   boards    cd        cp        edit      filesize  help      mkdir     rm        shell 
+   ```
+ - **[repl][micropython-repl]** command will start micropython interactive shell.
+   Also this shell can be used for board soft reboots(Ctrl+D). Hard reboots can be done by board "rst" button.
+
+
+## Board files/directories operations
+
+ - **[ampy][micropython-ampy]** utility can be used for storing/deleting files,
+   directories creation/removing and scripts run
+   ```bash
+   export AMPY_PORT=/dev/ttyUSB0
+   ampy mkdir /lib
+   ampy put blynklib.py /lib/blynklib.py
+   ampy put test.py test.py
+   ampy run test.py
+   ```
+
+
+## Micropython libraries compiltation 
+
+Micropython provides ability to compile source code into .mpy frozen module file
+Main advantage of this that .mpy files will consume less RAM compared
+to raw Python .py source files 
+
+For .mpy file compilation you need:
+ - get [mpy-cross][micropython-mpy-cross] tool
+   ```bash
+   git clone https://github.com/micropython/micropython.git
+   cd micropython/mpy-cross
+   make
+   ```
+ - optionally get heapsize of your board via **[repl][micropython-repl]**.
+   ```text
+   >>> import gc
+   >>> gc.collect()
+   >>> gc.mem_free()
+   2812256
+   ```
+ - compile source code and get .mpy file
+   ```bash
+   ./mpy-cross -X heapsize=2812256 blynklib.py
+   ```
+ - .mpy files in the same manner can be placed to board libs with **[ampy][micropython-ampy]**
+   as usual .py file
+   ```bash
+   ampy put blynklib.mpy /lib/blynklib.mpy
+   ```
+   and imported within user scripts
+   ```python
+   # start of user script
+   import blynklib
+   ```              
+
+
+  [esp32]: http://esp32.net
+  [esp32-banner]: https://i.ytimg.com/vi/30f1n9h3aSc/maxresdefault.jpg
+  [micropython-download]: http://micropython.org/download#esp32
+  [micropython-repl]: https://docs.micropython.org/en/latest/esp8266/tutorial/repl.html
+  [micropython-ampy]: https://github.com/pycampers/ampy
+  [micropython-rshell]: https://github.com/dhylands/rshell
+  [micropython-esptool]: https://github.com/espressif/esptool
+  [micropython-mpy-cross]: https://pypi.org/project/mpy-cross/