Skip to content

Board

Access RoboBoard specific features: settings storage, power, appearance, versions.

Code snippets

View board information
void setup() {
  // Print Board information
  Serial.printf("RoboBoard X%d\n", Board.getNumber());
  Serial.printf("Revision: %s\n", Board.getRevisionStr());
  if (Board.getNumber() == 4)
    Serial.printf("Driver version: %s\n", Board.getDriverVersionStr());
  Serial.printf("Software version: %s\n", Board.getSoftwareVersionStr());
  Serial.printf("Board name: %s\n", Board.getName());
  Serial.printf("Boot color: 0x%x\n", Board.getColor());
  Serial.printf("USB inserted: %s\n", Board.isUSB()  ? "Yes" : "No");
}
void loop() { }
Change appearance in Totem App
void setup() {
  // Change board display inside Totem App connect menu
  Board.setName("My Robot"); // Display name "My Robot"
  Board.setColor(Color::Red); // Display with red color
}
void loop() { }

Functions

Some functions contain async parameter to execute action in "background" with delay of 500ms. This is used to avoid blocking currently running code. By default it is set to false.
Calling settingsErase() may block code until flash operations are executed. Calling settingsErase(true) does not block the code and erase operation is performed in background.

Control

Control specific board features.

Board.restart()

Board.restart(async)

Restart ESP32 to reload running program. Same functionality as Reset button.
Parameter:
async - asynchronous restart. Default: false.

state Board.isUSB()

Check if USB cable is connected to the board.
Returns:
state - is USB plugged in yes / no [true:false].

🖼 Appearance

Functions for customizing certain robot appearance settings. Most important ones - name and color are intended to identify robot when connecting with Totem App. Changing color also sets default one for RGB lights during board power up.

Board.setName(name)

Set board (or robot) name. Visible during Totem App connection.
Default: RoboBoard X3/X4.
Parameter:
name - string (text) up to 30 characters.

Board.setModel(model)

Set 16-bit appearance identifier (robot model, MiniTrooper, RoboCar, ..).
Note: not used in Totem App.
Parameter:
model - 16-bit appearance identifier [0x0000:0xFFFF]

Board.setColor(red, green, blue)

Board.setColor(hex)

Set board color. Displayed upon board start (RGB lights) and Totem App connection.
Default: 0. If 0, RGB.colorTotem() is set instead.
Parameter:
🔴 red - amount of red color [0:255]
🟢 green - amount of green color [0:255]
🔵 blue - amount of blue color [0:255]
hex - 24-bit HEX color code [0x000000:0xFFFFFF].

string Board.getName()

Get board name. Visible during Totem App connection.
Returns:
string - configured board name.

number Board.getModel()

Get 16-bit appearance identifier (robot model, MiniTrooper, RoboCar, ..).
Returns:
number - 16-bit appearance identifier [0x0000:0xFFFF]

hex Board.getColor()

Get board color. Displayed upon board start (RGB light) and Totem App connection.
Returns:
hex - 24-bit HEX color code [0x000000:0xFFFFFF].

Versions

Functions to read hardware and software versions.

number Board.getNumber()

Get RoboBoard number (board type X3 or X4).
Returns:
number - board number [3:4].

number Board.getRevision()

string Board.getRevisionStr()

Get RoboBoard hardware revision (version). Printed on the board in format: vX.X.
Returns:
number - revision [10,11,30]. Format: 11 -> v1.1.
string - revision (text) [1.0,1.1,3.0].

number Board.getSoftwareVersion()

string Board.getSoftwareVersionStr()

Get RoboBoard software version (Totem Boards core).
Format: <arduino>-totem.<build>
• arduino - ESP32 Arduino core version.
• build - Totem API build number.
Returns:
number - 32-bit version value (major | minor | patch | build). Example: 0x02000E01.
string - version (text). Example: 2.0.14-totem.1.

number Board.getDriverVersion() X4 only

string Board.getDriverVersionStr() X4 only

Get RoboBoard X4 co-processor (driver) firmware version.
Returns:
number - version. Format: 150 -> 1.50.
string - version (text) 1.50.

Board settings

RoboBoard has some extra features that can be enabled in a few different ways. By default it's disabled to not intervene if using as development board (programming with Arduino).
Recommended to enable when using robotic kits (like MiniTrooper, RoboCar).
Some of the settings can be changed in Arduino IDE > Tools menu.

Features:

  • On/Off RoboBoard X3 3V3 power
  • Force RoboBoard X3 into charging mode when USB-C cable is plugged in
  • Display if board restarted due low battery (blink red LED)
  • Display battery state of charge during startup (RGB animation)
  • Play sound on board power on (motor tone)
  • Play sound on Totem App connect / disconnect (motor tone)
  • Animate RGB if Totem App is disconnected

System startup order:

  1. System power on
  2. Initial (default) setting values loaded
  3. Arduino framework initialized
  4. Saved settings (settingsSave()) loaded from flash memory
  5. Function initRoboBoard() is called. Loads Arduino IDE menu settings
  6. (X3 only) If setChargingMode(true), start charging mode and halt
  7. RoboBoard system started
  8. TotemApp.begin() gets called (if selected in Arduino IDE menu)
  9. Function setup() is called
  10. Start repeat function loop()

Arduino IDE menu

After settings are loaded from flash in step 4⃣, system overwrites them with ones configured in Arduino IDE > Tools menu (step 5⃣). Only settings selected as "Enabled" gets turned on. If selection is "Default" - Arduino menu item is ignored and value loaded in step 4⃣ is used.
Enabled settings will be loaded each time board is powered on and won't be disabled if settingsSave() is called. To turn setting off - select "Default" and upload the code again.

Force override

Step 5⃣ allows to specify setting values that should be used during board initialization in step 7⃣.
To override settings before system initialization - add function void initRoboBoard().
Note: if function void initRoboBoard() is added - Arduino IDE menu settings are ignored.

// Function called after loading configuration from memory
// and before system is initialized
void initRoboBoard() {
  // Configuration is loaded from memory
  Board.setChargingMode(false); // Disable X3 charging mode
  // System initialization is started and setup() is called
}
void setup() {
  // Board.getChargingMode() -> always returns false
}
void loop() {

}

💾 Save to memory

Calling settingsSave() will remember configured values as default ones and gets loaded each time in step 4⃣. Used when changing "Board settings" inside Totem App.

Board.settingsSave()

Board.settingsSave(async)

Store current configuration to flash.
Also called by Totem App board settings dialog.
Parameter:
async - asynchronous save. Default: false.

Board.settingsErase()

Board.settingsErase(async)

Erase whole configuration stored in flash.
Does not reset runtime settings. Only removes ones stored in flash memory.
After restart - factory default settings will be loaded.
Parameter:
async - asynchronous erase. Default: false.

Function list

Board.setEnable3V3(state) X3 only

Set state of RoboBoard X3 peripheral LDO regulator.
• Allows to disable external components for low power applications.
Provides power for: RGB lights, GPIO 3V3 pin, Qwiic port.
Parameter:
state - LDO regulator on / off [true:false]. Default: true.

Board.setChargingMode(state) X3 only

Enable RoboBoard X3 charging mode.
• Powers off board when USB-C cable is plugged in.
• Indicates charging process with RGB lights.
Not recommended to use when programming with Arduino. It prevents code from executing because USB-C cable will be plugged in.
Parameter:
state - turn on / off [true:false]. Default: false.

Board.setStatusRGB(state)

Enable board status RGB display.
• Show battery SOC with RGB animation during power on.
• Blink red LED if board shut down due low battery.
• Running RGB animation - Totem App not connected.
• Steady RGB color - Totem App connected.
Parameter:
state - turn on / off [true:false]. Default: false.

Board.setStatusSound(state)

Enable board status sounds (motor tone).
• Play pitch up sound when board is powered on.
• Play pitch up sound - Totem App connected.
• Play pitch down sound - Totem App disconnected.
Note: DC motors has to be connected to emit any sound.
Parameter:
state - Sound is on / off [true:false]. Default: false.

state Board.getEnable3V3() X3 only

Check if RoboBoard X3 3V3 LDO regulator is enabled.
Returns:
state - is enabled [true:false]. Default: true.

state Board.getChargingMode() X3 only

Check if RoboBoard X3 charging mode is enabled.
Returns:
state - is enabled [true:false]. Default: false.

state Board.getStatusRGB()

Check if board status RGB display is enabled.
Returns:
state - is enabled [true:false]. Default: false.

state Board.getStatusSound()

Check if board status sounds are enabled.
Returns:
state - is enabled [true:false]. Default: false.