API Reference

Application Programming Interface. A set of functions to control various board features.
It consists of standard ESP32 Arduino implementation with addition of Totem software for RoboBoard. This whole package allows to use it as standard Arduino development board with additional capabilities.

Note: Some features may be available with specific RoboBoard only. Such differences are marked with X3 only, X4 only tags.

Software structure

RoboBoard X3RoboBoard X4

Software package is divided into parts:

• Arduino API - official Arduino programming functions Arduino Reference.
  Universal across all Arduino boards. Used by third-party Arduino libraries.
• ESP32 API - processor specific functions and additional esp32-hal drivers.
  Ties ESP32 with Arduino framework and provides extended peripheral functionality.
• ESP-IDF - official Espressif development framework contains all ESP32 drivers.
  Layer between hardware and software. Provides all required tools and drivers for ESP32.
• RoboBoard API - additional RoboBoard functionality provided by Totemmaker.
  Includes board control functions totem-bsp and other services.

All software parts can be accessed from Arduino sketch, but mainly Arduino API and RoboBoard API is used.

Compile definitions

Most of the code works the same on RoboBoard X3 and RoboBoard X4. In case it's required to run different code per each board - use definitions to detect board type at compile time:

#if ROBOBOARD_X3 // Compiles only on RoboBoard X3
  pinMode(IO32, OUTPUT); // Initialize IO32 pin as output
#endif
#if ROBOBOARD_X4 // Compiles only on RoboBoard X4
  pinMode(GPIOA, OUTPUT); // Initialize GPIOA pin as output
#endif

Note: correct board must be selected in Arduino IDE Board menu.

Totem Prefix

If there is a conflict between Totem API function names and some library, this option requires to use prefix (C++ namespace) with every totem function:

• PlatformIO: In platformio.ini add: build_flags = -DREQUIRE_TOTEM_PREFIX
• Arduino IDE: Select Tools → Totem Prefix → totem::Board

void setup() {
    totem::Board.getRevision();
    totem::Battery.getVoltage();
    totem::RGB.color(totem::Color::Red);
}

Multithreading

RoboBoard Arduino implementation has function addLoop() to create additional parallel loop() tasks. An easy way to control separate actions with delay() function.
All tasks runs on the same Core 1, as main loop() and only single one is executed at the time.
Note: this is not a standard Arduino function and will not compile with other boards!

addLoop(function)

Register new parallel loop() function.
Parameter:
function - parallel function name (loop2())

int counter0 = 0;
int counter1 = 0;
int counter2 = 0;
int counter3 = 0;

void loop1() {
    if (counter1 <= 3) printf("loop1(): %d\n", counter1++);
}
void loop2() {
    if (counter2 <= 3) printf("loop2(): %d\n", counter2++);
}
void loop3() {
    if (counter3 <= 3) printf("loop3(): %d\n", counter3++);

}
void setup() {
    printf("setup()\n");
    addLoop(loop1);
    addLoop(loop2);
    addLoop(loop3);
}

void loop() {
    if (counter0 <= 3) printf("loop0(): %d\n", counter0++);
    // delay(0); // <- switch to other loop earlier
}

Loop functions will switch between by reaching end of function or call to delay(). Note that loop() has priority over added ones, so call to delay(0) is required to execute all loops equally. See print output bellow to view the difference:

Print output

Without delay(0)With delay(0)

setup()
loop0(): 0
loop0(): 1
loop0(): 2
loop0(): 3
loop1(): 0
loop2(): 0
loop3(): 0
loop1(): 1
loop2(): 1
loop3(): 1
loop1(): 2
loop2(): 2
loop3(): 2
loop1(): 3
loop2(): 3
loop3(): 3

setup()
loop0(): 0
loop1(): 0
loop2(): 0
loop3(): 0
loop0(): 1
loop1(): 1
loop2(): 1
loop3(): 1
loop0(): 2
loop1(): 2
loop0(): 3
loop2(): 2
loop3(): 2
loop1(): 3
loop2(): 3
loop3(): 3

Totem API list

Full list of functionalities and libraries available in Arduino environment for RoboBoard.

• TotemApp - Totem Android/iOS application for RoboBoard control
• Drivetrain - robot wheel control logic
• Joystick - raw joystick input converter
• Battery - acquire battery status
• Board - acquire RoboBoard information and change settings
• IMU - accelerometer & gyroscope readings
• RGB - RGB light controller
• LED - status LED controller
• Color - list of color names
• Button - physical button input controller
• IOLED - external LED controller connected to IO pin
• IOButton - external button controller connected to IO pin
• Servo - servo motor controller interface
• DC - DC motor controller interface
• TotemModule11 - TotemBUS Distance module X4 only
• TotemModule14 - TotemBUS Line Follower module X4 only
• TotemModule15 - TotemBUS Potentiometer module X4 only

• TotemModule22 - TotemBUS Environment sensor module X4 only

• addLoop(func) - function to create parallel loop() handler

• initRoboBoard() - RoboBoard system pre-initialization handler
• TOTEMMAKER_PLATFORM - Totem Arduino core for RoboBoard
• ROBOBOARD_X3 - board RoboBoard X3 is selected during compilation
• ROBOBOARD_X4 - board RoboBOard X4 is selected during compilation

Libraries

• #include <Totem.h> - remote RoboBoard control. Labboard control

Espressif API list

• ESP
• Arduino API reference
• APIs documentation
• FreeRTOS API Reference

HAL drivers

Additional ESP32 drivers, providing extended functionality compared to standard Arduino API.

• esp32-hal-adc.h
• esp32-hal-cpu.h
• esp32-hal-dac.h
• esp32-hal-i2c-slave.h
• esp32-hal-i2c.h
• esp32-hal-ledc.h
• esp32-hal-log.h
• esp32-hal-rgb-led.h
• esp32-hal-rmt.h
• esp32-hal-sigmadelta.h
• esp32-hal-spi.h
• esp32-hal-timer.h
• esp32-hal-touch.h
• esp32-hal-uart.h
• Low level drivers (esp-idf)
• All components (esp-idf)

Encoding / encryption

• base64 (#include )
• MD5Builder (#include )

For AES, RSA, SHA and others check: esp-idf

Libraries

• ArduinoOTA - upload ESP32 firmware binary over Wi-Fi
• BluetoothSerial - Bluetooth Classic Serial communication
• DNSServer - (CaptivePortal) display website when connected to ESP32
• EEPROM - legacy user data storage to flash
• ESP Insights - Espressif diagnostic cloud service
• ESP RainMaker - Espressif IOT cloud service
• ESP32 Async UDP - broadcast using UDP protocol
• ESP32 BLE Arduino - Bluetooth Low Energy communication
• ESPmDNS - host local website with address http://esp32.local
• FFat - FAT file system
• HTTPClient - access other websites (web browser)
• HTTPUpdate - firmware update from HTTP server
• HTTPUpdateServer - host local website to update firmware
• I2S - I2C peripheral control library
• LittleFS - LittleFS file system
• NetBIOS - make ESP32 discoverable on local network
• Preferences - library for long term user data storage
• SD - SD card control library
• SD_MMC - SD MMC card control library
• SimpleBLE - advertise basic BLE server
• SPI - SPI peripheral control library
• SPIFFS - SPIFFS file system
• Ticker - function call at specific rate
• Update - ESP32 firmware update library
• WebServer - host local website
• WiFi - WiFi control library
• WiFiClientSecure - connect to web server using TLS
• WiFiProv - WiFi provision over BLE or SOFTAP
• Wire - I2C peripheral control library