Installation guide for ESP32

README.md

@@ -15,7 +15,46 @@ This library generates an experiment configuration in this file format and allow
 
 ## Installation
 
-[TBD]
+### Install MicroPython Firmware
+1. Install the [Thonny Python IDE](https://www.thonny.org).
+2. Download the MicroPython-Firmware as `bin`-file for your ESP32 chip (e.g. https://micropython.org/download/esp32/).
+3. Connect your ESP32 microcontroller via USB to your computer.
+4. Open Thonny, go to the "Tools"-Menu and select "Options...".
+5. Go to "Interpreter" and select "MicroPython (ESP32)".
+6. Select the USB port connected to the ESP32 (e.g. "USB Serial (/dev/ttyUSB0)").
+7. Click on "Install or update MicroPython".
+8. Select the USB-Port and the firmware file. 
+9. Choose "Erase flash before installing" to delete the flash before installing the Firmware. 
+10. Click on "Install". The Installation takes a few minutes.
+11. After the firmware is written on the ESP32 close the "Options..." window and test the installation with a shell prompt (e.g. `print('Hello World!')`).
+![Installation of MicroPython on the ESP32 with Thonny IDE](output.gif)
+
+### Install Phyphox-BLE library
+1. Download the [Phyphox-BLE library](https://github.com/phyphox/phyphox-micropython/archive/refs/heads/main.zip) for MicroPython.
+2. Extract the zip-file.
+3. Connect your ESP32 via USB to your computer.
+4. Open Thonny.
+5. Select "Files" in the "View"-Menu of Thonny.
+6. Navigate to the directory with the extracted zip-file (`phyphox-micropython-main`).
+7. Left-click on the `phyphoxBLE` directory and select "Upload to /". The Phyphox-BLE is now uploading to the ESP32 chip.
+8. With the command `from phyphoxBLE import PhyphoxBLE, Experiment` you can now use the library.
+![Installation of the Phyphox-BLE library](BLEinstall.gif)
+
+### Test the Phyphox-BLE library
+1. Connect your ESP32 via USB to your computer and open Thonny.
+2. Open an example script from the `examples` directory of `phyphox-micropython-main` e.g. `randomNumbers.py`.
+3. Click on green Play button or press F5 to run the script on the ESP32.
+4. Open the Phyphox App on your phone.
+5. Add a new experiment (on Android by clicking on the Plus symbol). Select the "Bluetooth device" option.
+6. Select the device named "phyphox".
+7. Phyphox now starts the experiment. Press on play to see the random numbers generated by the ESP32.
+8. If you want to change the device name, stop the script by pressing the Stop button in Thonny.
+9. In line 7 add your device name in the brackets of the command `p.start()`.
+10. You can also change the time interval in which the random numbers are generated. Therefore change the milliseconds in line 13 of the script.
+11. Save the script and start it again by pressing the Play button in Thonny.
+12. Now you should see your device name when adding the bluetooth experiment in Phyphox.
+13. Customize the experiment by using the commands below.
+![Phyphox BLE example running on ESP32](BLEexample.gif)
 
 ## Usage
 

phyphoxBLE/experiment.py

@@ -1,8 +1,8 @@
 from io import StringIO
 
-phyphoxBleNViews      = 5
-phyphoxBleNElements   = 5
-phyphoxBleNExportSets = 5
+phyphoxBleNViews      = 8
+phyphoxBleNElements   = 8
+phyphoxBleNExportSets = 8
 
 class Experiment:
     def __init__(self):
@@ -280,10 +280,16 @@ def __init__(self):
         self._LABELX        = ""
         self._LABELY        = ""
         self._COLOR         = ""
+        self._COLOR2        = ""
+        self._COLOR3        = ""
+        self._COLOR4        = ""
         self._XPRECISION    = ""
         self._YPRECISION    = ""
         self._INPUTX        = "CH0"
         self._INPUTY        = "CH1"
+        self._INPUTY2       = ""
+        self._INPUTY3       = ""
+        self._INPUTY4       = ""
         self._STYLE         = ""
         self._XMLATTRIBUTE  = ""
 
@@ -302,6 +308,15 @@ def LABELY(self):
 
       def COLOR(self):
         return self._COLOR
+
+      def COLOR2(self):
+        return self._COLOR2
+
+      def COLOR3(self):
+        return self._COLOR3
+
+      def COLOR4(self):
+        return self._COLOR4
 
       def XPRECISION(self):
         return self._XPRECISION
@@ -314,6 +329,15 @@ def INPUTX(self):
 
       def INPUTY(self):
         return self._INPUTY
+
+      def INPUTY2(self):
+        return self._INPUTY2
+
+      def INPUTY3(self):
+        return self._INPUTY3
+
+      def INPUTY4(self):
+        return self._INPUTY4
 
       def STYLE(self):
         return self._STYLE
@@ -339,9 +363,15 @@ def setLabelY(self, strInput):
         self._ERROR = self.err_check_length(strInput,20,'setLabelY') if self._ERROR._MESSAGE is "" else self._ERROR
         self._LABELY = " labelY=\"" + strInput + "\""
 
-      def setColor(self, strInput):
+      def setColor(self, strInput, strInput2=None, strInput3=None, strInput4=None):
         self._ERROR = self.err_check_hex(strInput,'setColor') if self._ERROR._MESSAGE is "" else self._ERROR
         self._COLOR = " color=\"" + strInput + "\""
+        if strInput2 != None:
+            self._COLOR2 = " color=\"" + strInput2 + "\""
+        if strInput3 != None:
+            self._COLOR3 = " color=\"" + strInput3 + "\""
+        if strInput4 != None:
+            self._COLOR4 = " color=\"" + strInput4 + "\""
 
       def setXPrecision(self, intInput):
         self._ERROR = self.err_check_upper(intInput,9999,'setXPrecision') if self._ERROR._MESSAGE is "" else self._ERROR
@@ -351,11 +381,17 @@ def setYPrecision(self, intInput):
         self._ERROR = self.err_check_upper(intInput,9999,'setYPrecision') if self._ERROR._MESSAGE is "" else self._ERROR
         self._YPRECISION = " yPrecision=\"" + str(intInput) + "\""
 
-      def setChannel(self, intInputX, intInputY):
+      def setChannel(self, intInputX, intInputY, intInputY2=None, intInputY3=None, intInputY4=None):
         self._ERROR = self.err_check_upper(intInputX,5,'setChannel') if self._ERROR._MESSAGE is "" else self._ERROR
         self._ERROR = self.err_check_upper(intInputY,5,'setChannel') if self._ERROR._MESSAGE is "" else self._ERROR
         self._INPUTX = "CH" + str(intInputX)
         self._INPUTY = "CH" + str(intInputY)
+        if intInputY2 != None:
+            self._INPUTY2 = "CH" + str(intInputY2)
+        if intInputY3 != None:
+            self._INPUTY3 = "CH" + str(intInputY3)
+        if intInputY4 != None:
+            self._INPUTY4 = "CH" + str(intInputY4)
 
       def setStyle(self, strInput):
         self._ERROR = self.err_check_style(strInput,'setStyle') if self._ERROR._MESSAGE is "" else self._ERROR
@@ -376,13 +412,35 @@ def getBytes(self, buffer):
         buffer.write(self._XPRECISION)
         buffer.write(self._YPRECISION)
         buffer.write(self._STYLE)
-        buffer.write(self._COLOR)
         buffer.write(self._XMLATTRIBUTE)
         buffer.write('>\n')
-        buffer.write('\t\t\t<input axis=\"x\">')
+        buffer.write('\t\t\t<input axis=\"x\" ')
+        buffer.write(self._COLOR)
+        buffer.write('>')
         buffer.write(self._INPUTX)
         buffer.write('</input>\n\t\t\t<input axis=\"y\">')
         buffer.write(self._INPUTY)
+        if self._INPUTY2 != "":
+            buffer.write('</input>\n\t\t\t<input axis=\"x\" ')
+            buffer.write(self._COLOR2)
+            buffer.write('>')
+            buffer.write(self._INPUTX)
+            buffer.write('</input>\n\t\t\t<input axis=\"y\">')
+            buffer.write(self._INPUTY2)
+        if self._INPUTY3 != "":
+            buffer.write('</input>\n\t\t\t<input axis=\"x\" ')
+            buffer.write(self._COLOR3)
+            buffer.write('>')
+            buffer.write(self._INPUTX)
+            buffer.write('</input>\n\t\t\t<input axis=\"y\">')
+            buffer.write(self._INPUTY3)
+        if self._INPUTY4 != "":
+            buffer.write('</input>\n\t\t\t<input axis=\"x\" ')
+            buffer.write(self._COLOR3)
+            buffer.write('>')
+            buffer.write(self._INPUTX)
+            buffer.write('</input>\n\t\t\t<input axis=\"y\">')
+            buffer.write(self._INPUTY3)
         buffer.write('</input>\n\t\t</graph>\n')
 
     class Edit(Element):
@@ -640,3 +698,4 @@ def getBytes(self, buffer):
             buffer.write('\t</set>\n')
 
 
+

phyphoxBLE/phyphoxBLE.py

@@ -271,3 +271,4 @@ def start(self, device_name="phyphox", exp_pointer=None, exp_len=None):
 
 
 
+