Skip to content

Arduino setup

Arduino is a well known framework for integrated development environments. By using Arduino and Totem Library, a microcontroller can be programmed to use Totem modules for sensing or controlling external equipment, like motors and lights.

To start with Arduino, a development environment is required. Currently there are 2 most popular choices:

  • Arduino IDE - an original Arduino development environment with a basic functionality, but easy understandable for beginners.
  • PlatformIO - a development environment built on top of Visual Studio Code editor with all modern features like code indexing, autocomplete and much more for advanced users.

Requirements

This tutorial presumes you have RoboBoard X4 and the following guide will instruct how to setup a project with it. It's also possible to use third-party ESP32 boards.

Choose which one to continue with:

Arduino IDE Original Arduino IDE stands out with it's simple design, allowing to compile a project and upload it to the microcontroller. This is one of the reasons why it's so popular among beginners. Aside from basic functionality, it has thousands of third-party libraries and code examples to create a project even faster.

Warning

Make sure you are running Arduino version 1.8.13 or later. Older version won't work.

Bug

ESP32 Arduino Core contains a bug, that doesn't allow to compile the project (error: undefined reference).
Until a new version is released, Step 4 is required to patch existing version.

To setup environment:

Step 1: Install Arduino IDE.
Go to download page and install it.
Run Arduino IDE.

Step 2: Install Arduino ESP32 core.

  1. In Arduino IDE select FilePreferences.
  2. Locate Additional Boards Manager URLs and paste in:
    https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
  3. Click OK.
  4. Select ToolsBoardBoards Manager..
  5. In search field type in esp32.
  6. Select version 1.0.4 (1.0.5 is incompatible ant the moment).
  7. Click Install and wait for it to complete. It can take a few minutes.
  8. Close Boards Manager window.

Step 3: Install Totem Library

  1. Select SketchInclude LibraryManage libraries..
  2. In search field type in totem.
  3. Click Install and wait for it to complete.
  4. Close Library Manager window.
    Arduino IDE Library install

Step 4: Apply ESP32 core fix.

Windows

Click Win+R to open "Run" window.
Type "cmd" and click OK to open Command Prompt.
Run window
Copy command (Installer version):
copy /Y %HOMEPATH%\Documents\Arduino\libraries\Totem_Library\src\esp32\platform.txt %HOMEPATH%\AppData\Local\Arduino15\packages\esp32\hardware\esp32\1.0.4\platform.txt & exit
Copy command (Windows store version):
copy /Y %HOMEPATH%\Documents\Arduino\libraries\Totem_Library\src\esp32\platform.txt %HOMEPATH%\Documents\ArduinoData\packages\esp32\hardware\esp32\1.0.4\platform.txt & exit
Paste inside Command Prompt by clicking right mouse button on title bar and select EditPaste.
Click Enter. Command Prompt will close. Cmd window

MacOS

Open Terminal application.
Copy and paste inside Terminal:
cp ~/Documents/Arduino/libraries/Totem_Library/src/esp32/platform.txt ~/Library/Arduino15/packages/esp32/hardware/esp32/1.0.4/platform.txt; exit
Click Enter. Terminal will close.

To resolve Python problems with MacOS Big Sur refer this GitHub issue.

Step 5: Select development board.
Select ToolsBoardESP32 ArduinoESP32 Dev Module.
Leave other settings default:
Upload Speed: 921600
CPU Frequency: 240Mhz
Flash Frequency: 80Mhz
Flash Mode: QIO
Flash Size: 4MB
Partition Scheme: Default 4MB with spiffs
Core Debug Level: None
PSRAM: Disabled
Step 6: Load example.
Select FileExamples → (scroll down) → Totem LibraryX4LedBlink.
A new window with example code will open.
Step 7: Connect X4 board.
Connect X4 board to PC over USB cable and power it on.
Make sure the battery or DC jack is connected and power switch is turned on.
X4 is not powered from USB alone!
Status LED (middle) should be lit on. If it's slowly blinking - create a topic to resolve issue.
Step 8: Select port.
Select ToolsPort and click on the port displayed there.
If Port is not available - check if X4 is on and plugged to PC with USB cable.
If there are multiple ports, disconnect USB cable and check which one is gone. Reconnect and select it.
Step 9: Compile and upload code.
Select SketchUpload and wait till it completes (can take a few minutes first time).
At this stage code should compile without errors and upload to ESP32 board.
Status LED (middle) should be lit on. If it's slowly blinking - create a topic to resolve issue.
Step 10: Done.
Leds on RoboBoard X4 should start blinking.

Serial Monitor

To view text printed with Serial.print() functions:
Select ToolsSerial Monitor.
Set baud to 115200.

PlatformIO PlatformIO is built on top of industry leading Visual Studio Code editor. It supports many microcontroller architectures, development boards and can utilize all Arduino libraries. Furthermore, Visual Studio Code has all modern editor features like syntax highlighting, autocomplete, indexing, extensions and many more.

To setup environment:

  1. Follow install instructions on PlatformIO website.
    Wait for PlatformIO extension installation to finish.
  2. Read Quick start guide to familiarize a bit.
  3. Open PIO Home by clicking PlatformIO icon PlatformIO iconPIO HomeOpen.
    Note: sometimes you need to wait a bit for a button to appear on left side bar.
  4. Click + New Project. A window will open:
    PlatformIO new project
  5. Fill in fields:
    Name: type in any project name.
    Board: select Espressif ESP32 Dev Module.
    Framework: select Arduino Framework.
  6. Click Finish. and project will be created.
    Note: creating project first time can take a few minutes for all required toolchains to setup.
  7. Click PlatformIO icon → PIO HomeLibraries. In search bar type totemmaker.
  8. Select Totem Library from the list and add it to your project. PlatfomIO Totem Library
  9. In Examples tab select "X4\LedBlink".
    Example select
  10. Copy all LedBlink.ino file content to src/main.cpp file (located in Explorer).
    Note: select View → Explorer if you don't see project files list.
  11. Inside Explorer open project file platformio.ini.
  12. Add following lines to the end of the file and save it:
    monitor_speed = 115200
    monitor_filters = esp32_exception_decoder
    monitor settings Line "monitor_speed" will set Serial monitor baud to match Serial.begin(115200).
    Line "monitor_filters" will display exact location of error if ESP32 crashes.
    For more options read Project Configuration File.
  13. Change platform = espressif32 to:
    platform = espressif32@3.0.0 (newer version is incompatible at the moment)
  14. Connect X4 board to PC over USB cable and power it on.
    Make sure the battery or DC jack is connected and power switch is turned on.
    X4 is not powered from USB alone!
    Status LED (middle) should be lit on. If it's slowly blinking - create a topic to resolve issue.
  15. Select PlatformIO: Upload.
    At this stage code should compile without errors and upload to X4 board.
    First time compilation can take a few minutes.
    Some yellow warnings may be displayed during compilation. This does not indicate an error.
    Status LED (middle) should be lit on. If it's slowly blinking - create a topic to resolve issue.

Serial Monitor

To view text printed with Serial.print() functions:
Select PlatformIO: Serial Monitor

Tip

If you encountered an error during Connecting...., install CP210x driver.

To use non-Totem branded ESP32 development boards follow tutorial:

To learn more about functions used in the code:
Totem API - Totem library functions.
Arduino reference manual - standard Arduino framework functions.