Quercus User manual

(This is a work in progress. This line will be removed when the document is finished.)

The following are step by step instructions for making the ESP32/Dialog FPGA Quercus prototype system work and run a simple “blinky” application. Colored text pertains to the difference in steps when using a Quem80 prototype ESP32C3 hardware board vs an off the shelf ESP32 board in combination with a Dialog FPGA “DIP board” such as the SLG47004V-DIP.

Prerequisites:

  1. An Ubuntu Linux system or Windows WSL system running Ubuntu. Support for other Linux distros and OS types will be offered in response to demand.
  2. An ESP32 single board computer (regular and S2 types have been tested) and a Dialog SLG47004V-DIP or a Quem80 ESP32C3 board with socket for SLG47004V-DIP (plus that board).
  3. A long solderless breadboard
  4. 10cm or longer male to male and male to female solderless breadboard jumpers
  5. A 500-1500 ohm resistor
  6. An LED with Vf well below 3.3v such as a typical green type
  7. A micro USB cable for an ESP32 board or one (version 0.70) or two (version 0.60) mini USB cables for a Quem80 board. WARNING! The mating mini USB connectors on Quem80 boards are extraordinarily delicate. With thumb held on the connector gently insert the cable(s). Then >>> AVOID <<< ever removing the cable and >>> AVOID <<< bending the cable up close to the connector, creating a lever arm torquing the connector. Failure to follow these practices will result in the connector solder joints fracturing. A fix for this defect is in the todo list. Consult Nick Edgington or Pete Soper for advice about reinforcing the connector with various methods.

The TriEmbed repositories and user manual URLs:

  1. http://github.com/TriEmbed/que_league – A repository of general project data the DialogDesigns subdirectory of which holds example Dialog FPGA configurations.
  2. http://github.com/TriEmbed/que_tools – A repo holding the system build scripts and programs. Subdirectory linux contains script installit, currently at version 0.28, and this is the starting point for a system install.
  3. http://github.com/TriEmbed/que_ant – A repo holding C code that has node.js code added to it and that gets customized by an installation. This is the code that is compiled and linked and flashed into the ESP32 chip. This repo is automatically installed by the above installit script.
  4. http://github.com/TriEmbed/que_aardvark – A repo holding node.js code that provides a web-based local application with a web browser user interface. This application controls the que_ant code in the ESP32 to use it to program FPGAs connected to the ESP32 via an I2C bus. This repo is automatically installed by the above installit script.
  5. https://triembed.org/quercus-user-manual is this web page containing the user manual.
  6. The Espressif Integrated Development Framework (IDF) repo is automatically installed by the above installit script into $targetdir (defaults to ~)/esp-idf.

Downloading:

  1. Pick a convenient place for copies of the above repo directories such as your home directory (shorthand is ~ or $HOME) or any other pre-existing directory such as $HOME/quercus.
  2. Change directory to the one you have sellected such as with “cd $HOME”.
  3. Clone thetools and League repositories with these commands:
    1. git clone http://github.com/TriEmbed/thetools.git
    2. git clone http://github.com/TriEmbed/League.git

Installing:

  1. Change directory to subdirectory linux of the just cloned directory such as with “cd $HOME/thetools/linux”.
  2. Type “./installit -help” and study the usage information and help lines for the command. Notice the -targetdir command that takes a fully qualified (i.e. not relative like “..”) pathname to your repos. If your target directory is $HOME/quercus then you will have “-targetdir $HOME/quercus” as command line arguments to the installit command. Typical command lines look like this if the default user home directory is where everything is to be installed: ./installit <myrouterSSID> <myrouterPASSWORD> -targetdevice ESP32 or this: ./installit <myrouterSSID> <myrouterPASSWORD> -c3board 70.
  3. The script takes about 10 minutes to run the first time but is faster subsequent times by avoiding new clones of the IDF and its submodules.
  4. If the script fails with an error cut and paste the most recent text including the error message and send it to the Signal alphatest group. If you aren’t in this group but would like to be simply send the message to Pete Soper or Rob Mackie to be added.
  5. If the script failure is deemed mysterious you may be asked to edit it with a text editor to add a ” -x” to the first line. This enables a very verbose output. Add “>/tmp/log” to the command line running the script and send /tmp/log to the person requesting it.
  6. If the script runs to completion it will put out a series of instructions for next steps that look like this:
  1. To use the Espressif IDF in arbitrary places add this line to ~/.bashrc:
    . $targetdir/esp-idf/export.sh” >/dev/null 2>&1
  2. To use que_ant and aardvark programs first cd to $targetdir/que_ant and enter ‘idf.py flash’. Then enter ‘idf.py monitor’ and copy the IP address into your clipboard. The IP address is the set of four numbers folowing “sta ip:” in a line that will look something like this: esp_netif_handlers: sta ip: 192.168.12.196, mask: 255.255.255.0, gw: 192.168.12.1
  3. Use cntrl and ‘]’ to break out of monitor when you no longer need it.
  4. Then use a text edit to change file $targetdir/aardvark/src/api/project.js by replacing 192.168.100.150″ on line 63 with the IP in your clipboard.
  5. Then cd to $targetdir/aardvark and enter ‘npm run build’. The system is now c
    ompletely built and the above steps do not need to be repeated until a new relea
    se is used.
  6. The ESP32 was already started running que_ant with the “idf.py flash”. To start the aarvark application change directory to $targetdir/aardvark and enter ‘npm run serve’.
  7. Once the aardvark application is ready to use it’s last lines will look like this:
    App running at: Local: http://localhost:8080
  8. Now point your browser to http://localhost:8080 and use the images below to navigate through aardvark usage. NOTE: Depending on the state of the aardvark software it may be necessary to use the three horizonal lines button to drop down the main menu on the left side of the screen. In other cases this menu will already be shown and “stick” to the screen as shown in the images below.
After pointing browser to localhost:8080
IAfter pressing the three horizontal lines at the top of the screen
Screen after clicking on the menu drop down angle bracket
After clicking status
After clicking i2cScan
After clicking Test
After clicking Browse and choosing Dialog app file and selecting que_league/DialogDesigns/greenpack-test1.aap
After app has been loading into FPGA memory. The FPGA is now running with its configuration.

Triangle Embedded Interest Group