TotemApp
TotemApp.
object allows to interact with Totem App and get connection events or value changes when button is pressed. Combination of app button editor and RoboBoard programming creates ability to make custom remote controls for particular robot or embedded application.
Available for Android and iOS.
See guide Custom functions for more detail instructions on executing custom actions on app button press.
Related configuration functions: Board.setStatusRGB()
and Board.setStatusSound()
.
Enabled automatically if TotemApp
is used inside the code.
Enabling this feature increases compiled binary size by 800KB.
Code snippets
// Got Totem App specific event
void appEvent(int evt, int value) {
if (evt == TotemApp.evtFunctionA) {
Serial.print("Got '/0/functionA': "); Serial.println(value);
}
if (evt == TotemApp.evtConnect) {
Serial.println("Totem App connected");
}
if (evt == TotemApp.evtDisconnect) {
Serial.println("Totem App disconnected");
}
}
// Override function called on app button click
// Allows to modify value before RoboBoard processes it
bool appOverride(int cmd, int value) {
if (cmd == TotemApp.cmdPosA) { // Invert "/0/serv/posA" direction
Servo.A.spinPos(-value); // Set servo position
return false; // Block app command (override)
}
if (cmd == TotemApp.cmdPowerA) { // Limit "/0/dc/powerA" to [-50:50]
if (value >= -50 && value <= 50) return true; // Allow app command
// value is above limit. Constrain it
DC.A.spin(constrain(value, -50, 50)); // Write motor power
return false; // Block app command (override)
}
// Allow other app commands to be processed by RoboBoard
return true;
}
void setup() {
Serial.begin(115200);
// Register TotemApp event function
TotemApp.addEvent(appEvent);
// Register Totem App override function
TotemApp.addOverride(appOverride);
}
// Loop program
void loop() {
// Empty
}
Runtime control
TotemApp.begin() ¶
TotemApp.begin(
name
) ¶-
Start Totem App service. Board will be discoverable in connect menu.
Note: call to any otherTotemApp
function will enable this service internally, soTotemApp.begin()
is not mandatory.
Parameter:name
- (optional) change board name displayed in Totem App. TotemApp.disconnect() ¶
-
Force to disconnect Totem App.
state
TotemApp.wait()
¶
state
TotemApp.wait(time
) ¶-
Wait for Totem App to connect (block code until).
Parameter:time
- maximum time to wait (ms) for app connection.0
- disabled.
Returns:state
-true
if connected,false
if timeout.
Receive events
Warning
At the moment evtFunction
is only available with Android version of Totem App.
Use Override commands as an alternative for iOS.
TotemApp.addEvent(
function
) ¶-
Register function to receive data sent from Totem App. Available event types:
•evtFunctionA
- topic/0/functionA
data received.
•evtFunctionB
- topic/0/functionB
data received.
•evtFunctionC
- topic/0/functionC
data received.
•evtFunctionD
- topic/0/functionD
data received.
•evtConnect
- Totem App connected.
•evtDisconnect
- Totem App disconnected.
Parameter:
function
- function name [appEvent
].
void appEvent(int evt, int value) { if (evt == TotemApp.evtFunctionA) { Serial.print("Function A: "); Serial.println(value); } if (evt == TotemApp.evtFunctionB) { Serial.print("Function B: "); Serial.println(value); } if (evt == TotemApp.evtFunctionC) { Serial.print("Function C: "); Serial.println(value); } if (evt == TotemApp.evtFunctionD) { Serial.print("Function D: "); Serial.println(value); } if (evt == TotemApp.evtConnect) { Serial.println("Totem App connected"); } if (evt == TotemApp.evtDisconnect) { Serial.println("Totem App disconnected"); } } void setup() { Serial.begin(115200); TotemApp.addEvent(appEvent); // Register TotemApp event function } void loop() { }
Override commands
Functionality allowing to intercept commands sent by Totem App. Typically button press will apply motor power directly (e.g. /0/dc/powerA
→ DC.A.power()
). Any action will be presented in bool appOverride(int cmd, int value)
function, providing value
and ability to choose either block or allow RoboBoard to process this command.
Can be used to intercept standard "Model" controls and make your own drive logic or actions.
List of app commands:
• TotemApp.cmdPosA
- topic /0/serv/posA
.
• TotemApp.cmdPosB
- topic /0/serv/posB
.
• TotemApp.cmdPosC
- topic /0/serv/posC
.
• TotemApp.cmdPowerA
- topic /0/dc/powerA
.
• TotemApp.cmdPowerB
- topic /0/dc/powerB
.
• TotemApp.cmdPowerC
- topic /0/dc/powerC
.
• TotemApp.cmdPowerD
- topic /0/dc/powerD
.
• TotemApp.cmdFunctionA
- topic /0/functionA
.
• TotemApp.cmdFunctionB
- topic /0/functionB
.
• TotemApp.cmdFunctionC
- topic /0/functionC
.
• TotemApp.cmdFunctionD
- topic /0/functionD
.
Known behavior
Totem App always sends cmdPowerA
, cmdPowerB
, cmdPowerC
, cmdPowerD
as a single message. Even if /0/dc/powerA
is the only one set - others will trigger event with value 0
.
TotemApp.addOverride(
function
) ¶-
Register function to override commands sent from Totem App.
Function declaration:bool appOverride(int cmd, int value)
cmd
- command identifier.value
- integer sent from app.
Usereturn false
to block command andreturn true
to allow it.
Parameter:
function
- function name [appOverride
].
Note: this function is called from Bluetooth environment, running on Core 0. It is not recommended to use heavy operations (like print or delay) inside function body.// Override function called on app button click bool appOverride(int cmd, int value) { if (cmd == TotemApp.cmdPosA) { Serial.print("/0/serv/posA -> "); Serial.println(value); } if (cmd == TotemApp.cmdPosB) { Serial.print("/0/serv/posB -> "); Serial.println(value); } if (cmd == TotemApp.cmdPosC) { Serial.print("/0/serv/posC -> "); Serial.println(value); } if (cmd == TotemApp.cmdPowerA) { Serial.print("/0/dc/powerA -> "); Serial.println(value); } if (cmd == TotemApp.cmdPowerB) { Serial.print("/0/dc/powerB -> "); Serial.println(value); } if (cmd == TotemApp.cmdPowerC) { Serial.print("/0/dc/powerC -> "); Serial.println(value); } if (cmd == TotemApp.cmdPowerD) { Serial.print("/0/dc/powerD -> "); Serial.println(value); } // This function requires return! // `true` - pass received command back to RoboBoard // `false` - RoboBoard won't get this command (override) return false; } // Initialize program void setup() { Serial.begin(115200); // Register Totem App override function TotemApp.addOverride(appOverride); } // Loop program void loop() { // Empty }