Skip to content

BLE

Provides wireless communication with Totem modules. This interface can be used whit any BLE capable ESP32 development board to control Totem modules, even from multiple connections. Interface provides all required functionality to discover Totem robots and connect them. Modules are able to represent themselves as "robot", providing name, color, model (type of robot). This information is available before BLE connection is established.

void setup() {
  Totem.BLE.begin(); // Initialize Bluetooth Low Energy interface
}

Functions list

Result Function Description
none begin() Initialize interface
TotemRobot findRobot() Blocking find and connect
none findRobotNoBlock() Non-blocking find and connect
bool isFinding() Check if find process is active
none stopFind() Stop find process
none attachOnConnect(RobotReceiver) Register on robot connected function
int getConnectedCount() Get active connections count
TotemRobot getConnectedLast() Get last connected robot
TotemRobot[] getConnectedList() Get active connections list

Example

// Include Totem library
#include <Totem.h>
// Use MiniTrooper as example robot
TotemMiniTrooper mini;
// User defined function that receives all discovered Totem robots
void onFoundRobot(TotemRobot robot) {
  // Check each found robot and connect to only whose name is "MyRobot"
  // For String reference check: https://www.arduino.cc/reference/en/language/variables/data-types/stringobject/
  if (robot.getName().compareTo("MyRobot") == 0) {
    // Start BLE connection to selected robot.
    if (robot.connect())
      Serial.println("Robot connected");
    else
      Serial.println("Robot connection failed");
    // After successfully connected, findRobot(onFoundRobot) will unblock and application proceeds
  }
}

void setup() {
  // put your setup code here, to run once:
  Totem.BLE.begin(); // Initialize Bluetooth Low Energy interface
  // Totem.BLE.findRobot(); // Optional: automatically connect to first discovered Totem robot
  Totem.BLE.findRobot(onFoundRobot); // Start searching over BLE. This function will block until connected to any 
                                     // Totem robot. After connection is successful, loop() will be executed.
                                     // onFoundRobot will list every discovered robot.
}

void loop() {
  // put your main code here, to run repeatedly:
  // Example to open and close flipper on MiniTrooper
  mini.flipperOpen();
  delay(1000);
  mini.flipperClose();
  delay(1000);
}

API

Functions

begin()

Initialize Bluetooth Low Energy interface. Must be executed inside setup() function before using library.
void setup() {
  Totem.BLE.begin(); // Initialize Bluetooth Low Energy interface
}

findRobot()

findRobot(RobotReceiver)

Start searching for available Totem robots over Bluetooth Low Energy. This function will block until connection to any robot is established.
On successful connection find process will be stopped. Additionally it can be stopped with call to stopFind().
RobotReceiver is a user defined function to get all discovered robots.
Format: void onFoundRobot(TotemRobot robot). Robot information can be accessed trough TotemRobot parameter. By calling robot .connect() user can decide which robot to select.
Parameter:
() - automatically connect to first discovered Totem robot.
RobotReceiver - discovered robot connect function onFoundRobot.
Returns: TotemRobot.
void onFoundRobot(TotemRobot robot) {
  // Totem robot discovered
  robot.connect();
}
void function() {
  Totem.BLE.findRobot(); // Automatically connect to first discovered Totem robot
  Totem.BLE.findRobot(onFoundRobot); // List result in onFoundRobot before connecting to Totem robot
}

findRobotNoBlock()

findRobotNoBlock(RobotReceiver)

Start searching for available Totem robots over Bluetooth Low Energy. This function does not block main program execution. All connection process will be done in background.
After connection is established, this process will be stopped. Additionally it can be stopped with call to stopFind().
RobotReceiver is a user defined function to get all discovered robots.
Format: void onFoundRobot(TotemRobot robot). Robot information can be accessed trough TotemRobot parameter. By calling robot .connect() user can decide which robot to select.
Parameter:
() - automatically connect to first discovered Totem robot.
RobotReceiver - discovered robot connect function onFoundRobot.
void onFoundRobot(TotemRobot robot) {
  // Totem robot discovered
  robot.connect();
}
void function() {
  Totem.BLE.findRobotNoBlock(); // Automatically connect to first discovered Totem robot
  Totem.BLE.findRobotNoBlock(onFoundRobot); // List result in onFoundRobot before connecting to Totem robot
}

isFinding()

Check if findRobot() or findRobotNoBlock() was called and process is active.
Returns: discovery process is active [true:false].
void function() {
  if (Totem.BLE.isFinding())
    Serial.println("Robot find is active");
  else
    Serial.println("Robot find is inactive);
}

stopFind()

Stop searching for robot and unblock findRobot(). Only used when required to stop this process manually. After connection, the search process is stopped automatically and calling this function is not required.
void function() {
  Totem.BLE.stopFind(); // Stop searching for robot over Bluetooth Low Energy
}

attachOnConnect(RobotReceiver)

Register function that will be called when findRobot() process connects to a robot. This is handy when using non-blocking find process and we don't know when connection is established.
RobotReceiver is a user defined function to connected robot event.
Format: void onConnectedRobot(TotemRobot robot). Robot information can be accessed trough TotemRobot parameter.
Parameter: RobotReceiver - connected robot event function onConnectedRobot.
void onConnectedRobot(TotemRobot robot) {
  // findRobotNoBlock connected to robot in background and ended find procedure
  Serial.print("Connected robot: ");
  Serial.println(robot.getName());
}
void function() {
  Totem.BLE.findRobotNoBlock(); // Automatically connect to first discovered Totem robot
                                // Code execution continues with active find procedure
}

getConnectedCount()

Count of currently connected Totem robots.
Returns: connected robots count [0:20]
void function() {
  Serial.print("Currently connected robots count: ");
  Serial.println(Totem.BLE.getConnectedCount());
}

getConnectedLast()

Get last connected robot.
If no connection was made before, this function returns a dummy object that isn't connected.
Returns: TotemRobot.
void function() {
  TotemRobot robot = Totem.BLE.getConnectedLast();
  Serial.print("Is last connected robot still connected: ");
  Serial.println(robot.isConnected() ? "Yes" : "No");
}

getConnectedList()

Get list of connected robots.
Returns: TotemRobot[].
void function() {
  for (auto robot : getConnectedList()) {
    Serial.print("Connected robot: ");
    Serial.println(robot.getName());
  }
}