Skip to content

[04] RoboBoard X4

Programmable robotics controller with Bluetooth connectivity, motor drivers and sensors input. For full feature description read X4 features.

TotemModule module(04);

Module image

Module commands

Before start

• Install programming environment by following tutorial on Arduino setup.
• Join our community forum for any questions: https://forum.totemmaker.net.

Command naming convention

Some commands controls various channels (A, B, C, ...). There is a logic behind command naming for flexibility:
write("commandA", 10) - will set value 10 for individual channel A.
write("commandAll", 100) - will set value 100 for all existing channels.
write("commandABCD", 10, 20, 30, 40) - will set individual values for A, B, C, D channels.
write("commandABC", 10, 20, 30) - will set individual values for A, B, C channels.
Only commands listed in "Module commands" will be accepted. Other variations will be discarded.
All commands are case sensitive! Calls like CommandA, COMMANDa, motorA/BRAKE will be ignored.

Alternate function call

Code running inside X4 can be called directly with Totem.X4.write("command") instead of generic module object module.write("command").

Configuration

Commands starting with "cfg" retains it's value after module power off. Used as module configuration parameters.

cfg/robot/name ( string )

Description: Configure robot name visible during connection.
Value: Any string value up to 30 bytes max. Default is "Totem X4".
module.write("cfg/robot/name", "My robot"); // Set robot name

cfg/robot/model ( int )

Description: Configure Totem robot model (MiniTrooper, Truck, ...).
Used to identify type of the robot. Can be configured to any value by user. Also received with getModel().
Value can be generated with command: TotemModule::hashModel("model").
Value: 16bit hash of robot model name. Default is 0.
// Set robot model to Truck
module.write("cfg/robot/model", TotemModule::hashModel("Truck"));
// Check if robot is Truck
ModuleData data;
if (module.readWait("cfg/robot/model", data) &&
    data.getInt() == TotemModule::hashModel("Truck")) { }

cfg/robot/color ( int )

Description: Configure robot color.
Used to recognize robot appearance by it's color. It may be displayed inside mobile application or on-board RGB LED.
Value: 24bit RGB color value (without brightness). Default is 0.
module.write("cfg/robot/color", 0x0000FF); // Set robot color to BLUE
// Alternative to set individual RGB colors:
module.write("cfg/robot/color", 0, 0, 255); // Set robot color to BLUE

cfg/motorABCD/invert ( int , int , int , int )

Description: Configure motor output polarity.
Individual motors can be configured to invert it's spinning direction. Allows to fix reversed motor wiring without reconfiguring robot controls.
Value: 0 or 1 per each channel. Default is 0.
// Invert channels A and B. C, B - not inverted (default).
module.write("cfg/motorABCD/invert", 1, 1, 0, 0);

cfg/motorABCD/autobrake ( int , int , int , int )

Description: Configure motor outputs autobraking feature.
When channel power is set to 0, an electronic motor brake will be applied.
Can be configured with different percentage of braking power per each channel.
Value: 0 to 100 per each channel. Default is 0.
// Set channels A, B to 100% brake power, C to 50%, D - no braking.
module.write("cfg/motorABCD/autobrake", 100, 100, 50, 0);

cfg/reset ( )

Description: Reset all module configuration to factory default.
module.write("cfg/reset"); // Reset all module settings to default

DC motor control

motorA ( int )

motorB ( int )

motorC ( int )

motorD ( int )

Description: Set individual DC motor A, B, C, D channel power.
Value: Percentage of power 0-100%. Negative value will spin backwards.
module.write("motorA", 100); // Write channel A

motorABCD ( int , int , int , int )

Description: Set all motor channels with one command call.
Value: Percentage of power 0-100%. Negative value will spin backwards.
module.write("motorABCD", 100, 50, 0, -100); // Write channels A, B, C, D

motorA/brake ( int )

motorB/brake ( int )

motorC/brake ( int )

motorD/brake ( int )

Description: Apply individual DC motor A, B, C, D channel brake power.
Value: Percentage of brake power 0-100%. Only positive value is accepted.
module.write("motorA/brake", 100); // Set channel A brake power to 100%

motorABCD/brake ( int , int , int , int )

Description: Apply brake to all DC motor channels with one command at the same moment.
Value: Percentage of brake power 0-100%. Only positive value is accepted.
module.write("motorABCD/brake", 100, 50, 0, 0); // Brake channels : A - 100%; B - 50%; C, D - no brake

Servo motor control

servoABC ( int , int , int )

Description: Set individual servo motor channels A, B, C with one command at the same moment.
Value: Position of servo angle. Value from -100 to 100. It maps to 0° to 180°. 0 equals 90°.
module.write("servoABC", 100, 50, -100); // Write channels A, B, C

servoA ( int )

servoB ( int )

servoC ( int )

Description: Set servo A, B, C channel position.
Value: Position of servo angle. Value from -100 to 100. It maps to 0° to 180°. 0 equals 90°.
module.write("servoA", 0); // Set servo channel A to 90° angle

On-board features

led ( int )

Description: Set on-board indication led state.
Value: Turn led on (true or 1) or off (false or 0).
module.write("led", true); // Turn on-board indication led on

button ( )

Description: Get state of on-board button. Read it once or subscribe to receive an event when button is pressed. This command is read-only.
Result: Button is pressed (true or 1) or released (false or 0).
bool buttonIsPressed = module.readWait("button"); // Read button state
// 'readWait' will delay code execution until result is received from the module.
ModuleData data; // Prepare variable to store read result
module.readWait("button", data); // Perform read with wait until result is received
bool buttonIsPressed = data.getInt(); // Get button state from result
// Function that will receive all subscribed commands of X4 module
void onModuleData(ModuleData data) {
    if (data.is("button")) { // Check if received command is "button"
        bool buttonIsPressed = data.getInt(); // Get button state
        Serial.print("Button state = ");
        Serial.println(buttonIsPressed?"PRESS":"RELEASE");
    }
}
void setup() {
    module.attachOnData(onModuleData); // Register onModuleData function
    module.subscribe("button"); // Subscribe to receive any state change of button
}

battery ( )

Description: Get connected battery voltage. This command is read-only.
If returned value is 0 - battery is not connected.
Result: Voltage in millivolts. Divide by 1000 to get volts.
// Read battery voltage
int voltage = module.readWait("battery").getInt(); // Result: 11350 -> 11.350V
// 'readWait' will delay code execution until result is received from the module.
ModuleData data; // Prepare variable to store read result
module.readWait("battery", data); // Perform read with wait until result is received
bool voltage = data.getInt(); // Get battery value from result. 11350 -> 11.350V
// Function that will receive all subscribed commands of module
void onModuleData(ModuleData data) {
    if (data.is("battery")) { // Check if received command is "battery"
        bool voltage = data.getInt(); // Get battery value from result. 11350 -> 11.350V
        Serial.print("Battery voltage = ");
        Serial.println(voltage);
    }
}
void setup() {
    module.attachOnData(onModuleData); // Register onModuleData function
    module.subscribe("battery"); // Subscribe to receive any state change of battery
}

RGB leds

rgbAll/totem ( )

Description: Set all RGB leds to Totem colors.
module.write("rgbAll/totem"); // Light all RGB leds to Totem colors

rgbAll/reset ( )

Description: Reset all RGB leds to default color.
Sets to color configured in cfg/robot/color command. If color is not configured, defaults to Totem colors.
module.write("rgbAll/reset"); // Light all RGB leds to default color

rgbAll ( int , int , int , int )

Description: Set all RGB leds color.
Value: Parameters:
1. Brightness - Value [0:255] indicates how bright led will shine.
2. Red - Value [0:255] indicates amount of red color.
3. Green - Value [0:255] indicates amount of green color.
4. Blue - Value [0:255] indicates amount of blue color.
module.write("rgbAll", 255, 0, 255, 0); // Set all leds to GREEN color
module.write("rgbAll", 0xFF, 0, 0xFF, 0); // Set all leds to GREEN color
module.write("rgbAll", 0xFF00FF00); // Set all leds to GREEN color

rgbA ( int , int , int , int )

rgbB ( int , int , int , int )

rgbC ( int , int , int , int )

rgbD ( int , int , int , int )

Description: Set individual RGB channels A, B, C, D led color.
Value: Parameters:
1. Brightness - Value [0:255] indicates how bright led will shine.
2. Red - Value [0:255] indicates amount of red color.
3. Green - Value [0:255] indicates amount of green color.
4. Blue - Value [0:255] indicates amount of blue color.
module.write("rgbA", 255, 0, 255, 0); // Set RGB A led to GREEN color
module.write("rgbA", 0xFF, 0, 0xFF, 0); // Set RGB A led to GREEN color
module.write("rgbA", 0xFF00FF00); // Set RGB A led to GREEN color

GPIO

Pin change event

GPIO pins can be set to detect pin state changes. This is done using subscribe command:

void onModuleData(ModuleData data) {
    if (data.is("gpioA")) {
        if (data.getInt() == HIGH)
            Serial.println("gpioA: HIGH");
        else
            Serial.println("gpioA: LOW");
    }
}

void setup() {
    // Enable serial print
    Serial.begin(115200);
    // Initialize X4 module
    Totem.X4.begin();
    // Register onModuleData function to receive events
    Totem.X4.attachOnData(onModuleData);
    // Subscribe to receive gpioA pin changes
    Totem.X4.subscribe("gpioA");
}

gpioA ( int )

gpioB ( int )

gpioC ( int )

gpioD ( int )

Description: Write or read GPIO pin A, B, C, D. Works similar like digitalWrite() and digitalRead() functions in Arduino.
Calling write or read will reconfigure pin to input or output automatically.
Value: [LOW:HIGH] - digital output between GND (0V) and VCC (3.3V).
// Configure GPIO pin A to output and set to HIGH
module.write("gpioA", HIGH);
// Configure GPIO pin A to input and read it's digital state (HIGH or LOW)
int gpioAState = module.readWait("gpioA").getInt();

gpioA/analog ( int )

gpioB/analog ( int )

gpioC/analog ( int )

gpioD/analog ( int )

Description: Write or read analog value of GPIO pin A, B, C, D. Works similar like analogWrite() and analogRead() functions in Arduino.
Calling write or read will reconfigure pin to analog input or output automatically.
Value read: [0:1024] - value representing voltage. 0 - 0V; 1024 - 3.3V.
Value write: [0:20] - value representing voltage. 0 - 0V; 20 - 3.3V.
// Configure GPIO pin A to analog output and set voltage to 1.6V
module.write("gpioA/analog", 10);
// Configure GPIO pin A to analog input and read analog value
int gpioAValue = module.readWait("gpioA/analog").getInt();

gpioA/pull ( int )

gpioB/pull ( int )

gpioC/pull ( int )

gpioD/pull ( int )

Description: Set pullup or pulldown resistor for GPIO pin A, B, C, D. Works similar like pinMode(pin, INPUT_PULLUP) function in Arduino.
Value write: [LOW:HIGH] - LOW - pull to GND (0V); HIGH - pull to VCC (3.3V).
// Read GPIO A
module.readWait("gpioA").getInt(); // Will return LOW
// Set GPIO pin A pull to VCC (3.3V).
module.write("gpioA/pull", HIGH);
// Read GPIO A
module.readWait("gpioA").getInt(); // Will return HIGH
// Set GPIO pin A pull to GND (0V).
module.write("gpioA/pull", LOW);
// Read GPIO A
module.readWait("gpioA").getInt(); // Will return LOW

Auxiliary functions

functionA ( any )

functionB ( any )

functionC ( any )

functionD ( any )

Description: Auxiliary commands for custom implementations.
Mainly used to execute some programmed action from a smartphone. Device calls this command with any value and X4 board intercepts it using subscription mechanism.
void onModuleData(ModuleData data) {
    if (data.is("functionA")) { // Check if received "functionA" event.
        Serial.print("Command 'functionA' called with value: ");
        Serial.println(data.getInt()); // Print value passed with command.
    }
}
void setup() {
    Totem.X4.begin(); // Initialize X4 module
    Totem.X4.attachOnData(onModuleData); // Register event function "onModuleData"
    Totem.X4.subscribe("functionA"); // Subscribe to command "functionA" events.
}