Note: the kit can not be reverted to our original behavior code using the Arduino IDE. For that, please see the Visual Studio Code section.
-Download and install the Arduino IDE application: https://www.arduino.cc/en/software
-Download and install the CH340 USB driver: http://www.wch-ic.com/downloads/CH341SER_ZIP.html
-Download code template: https://github.com/dietervandoren/komorebi-kit
Preparing the Arduino IDE software for ESP32 boards:
– Start the Arduino IDE software and go to File> Preferences
– In the Additional Boards Manager URLs field, enter (or copy-paste): https://dl.espressif.com/dl/package_esp32_index.json and click OK.
– Go to Tools> Board> Boards Manager …
– Enter “ESP32” in the search field and click Install in the search result “ESP32 by Espressif Systems”
– The board definitions are now downloaded and installed. INSTALLED appears when it is ready.
The Arduino IDE is now prepared to program ESP32 microcontrollers. (See also online guide here.)
Install and configure Mozzi library:
– In the Arduino IDE, go to File> Preferences
– Look in the “Sketchbook location” field to see the working directory of the Arduino IDE on your system.
– Go to this folder with your file browser (File Explorer / Finder). Inside it go into the folder “libraries”.
– From the downloaded code template, copy the folder “Mozzi” found inside the “lib” folder and paste into the Arduino “libraries” folder.
The Mozzi synthesis library is now ready to use with the kit hardware in the Arduino IDE.
Note: the Mozzi library that we included in our code template is already configured to output on the PT8211 external DAC instead of the regular PWM pin. If one were to download Mozzi afresh from https://github.com/sensorium/Mozzi then configurations have to be modified in the file “AudioConfigESP32.h”.
Code template explained:
The Arduino sketch in the folder “arduino_ide_template” is a minimal example of how to program the hardware using the Arduino IDE. The installation steps above are required (except for the Mozzi library in case one wishes to use other methods for producing audio signals). Every step is commented in the sketch code.
The sketch generates a sine wave with variable frequency dependent on the intensity of light input. The main elements are explained below.
Photodiode light sensor pre-amp gain and input:
The HT7833 photodiode is connected to an MCP6001 op-amp to convert its current output to a voltage received on pin 34 of the ESP32 microcontroller. The gain of the op-amp is variable to accommodate a wide range of lighting situations. The gain is set using a MCP4151 digital potentiometer via the SPI protocol. SPI slave select pin on the microcontroller is number 5. The SPI library must be included.
The gain is set through an 8 bit value with reversed range, meaning 255 is minimum gain and 0 is maximum gain. 255 is applicable for direct sunlight and 0 for twilight or candle light, with a wide spectrum in between to adapt to other situations.
The digitalPotWrite() function takes care of the SPI messaging.
Audio output amplifier enabling:
The kit includes a PT8211 digital-analog converter (DAC) which is automatically configured by the Mozzi library. To output sound on the embedded amplifier and speaker the PAM8302 amp IC has to be enabled first. It is disabled by default. Setting microcontroller pin 17 high enables the amp. Low disables (which can be useful for power saving).
The amplifier has a fixed gain. Output volume is regulated by setting the gain on the digital output signal generated by Mozzi.
Mozzi audio signal synthesis:
We use the Mozzi library to generate audio signals on a microcontroller like the ESP32. It’s an advanced library that provides many familiar synthesis functionalities like wavetables, oscillators, modulators, envelopes, etc. It also deals with the low level technicalities of outputting optimally on the microcontroller hardware, which can be a very complex affair.
Including MozziGuts.h is required. Other Mozzi header files are required depending on which functionalities are used. The template only uses a basic oscillator for which Oscil.h is included, as well as a sine wavetable. A sine object to reference in further code is created.
In setup(), startMozzi() enables audio processing.
Mozzi only requires calling audioHook() inside the loop().
All other Mozzi operations are performed in the functions updateControl() and updateAudio(). updateAudio() runs at audio rate (very fast) and should only contain the necessary audio sample calculations. updateControl() runs at a slower pace set with the CONTROL_RATE constant. Reading sensors, calculating synthesis parameters, printing serial messages, etc should be done in here whenever possible to not slow down the processor with unnecessary operations.
In updateControl(), we are first reading the light sensing input value, then mapping it to a sine frequency range. The frequency of the sine object is then set using setFreq().
In updateAudio() we are just retrieving the next sine wave sample value from the sine object with next(). Mozzi takes care of giving the right value given the frequency that we have set.
With the return command we pass the sample value to the audio output buffer. Before outputting the amplitude is raised by bit shifting left/up. That’s a computationally cheap method for multiplying by powers of 2. The output resolution of the DAC is 16 bit while the sine wavetable contains 8 bit values, meaning much of the available amplitude/resolution is not used. Therefore the amplitude is raised to get a good output volume.
The Mozzi library includes many examples to browse and explore.
Note: the Mozzi examples assume the standard 8 bit PWM output method. Most will require raising the output amplitude to yield a usable signal on the 16 bit kit hardware. Any Mozzi example will also require adding the amplifier enable code before the hardware will output sound.
Uploading code from the Arduino IDE:
Connect the USB cable and turn on the kit power switch.
Select “LOLIN D32” board type in Tools > Board > ESP32 Ardiuno
Select the serial port in Tools > Port
Click the upload button. When the code is compiled the IDE will try to flash the firmware onto the ESP32. Due to production tolerances on the hardware components some kits will flash automatically while others require a button press combination.
If a growing line of dots and underscores appears it means the button combination has to be performed. On the kit, hold the flash button while pressing and releasing the reset button. When uploading begins, release the flash button.
When uploading is completed, press the reset button.