SoftBank Robotics documentation What's new in NAOqi 2.5?

ALAutonomousLife API

NAOqi Interaction engines - Overview | API | Launch trigger conditions | Advanced

Namespace : AL

#include <alproxies/alautonomouslifeproxy.h>

Methods

void ALAutonomousLifeProxy::setState(const std::string& state)

Lets the developer manually set limited state changes in AutonomousLife. For futher details, see: States.

When changing the state to “disabled” or “safeguard”, stopAll() is called internally.

Note Manual change from interactive to solitary state will fail.

Parameters:
  • state – Can be one of the States.
std::string ALAutonomousLifeProxy::getState()

Retrieves the current state of AutonomousLife.

Returns:Can be one of the States.
void ALAutonomousLifeProxy::setRobotOffsetFromFloor(const float& offset)

Allows you to set if the robot is on the floor, or higher up such as on a table.

This notably have an effect on how the robot search for humans with Basic Awareness. Set it correctly to enhance tracking success.

The default offset is 0.

Parameters:
  • offset – A float value in meters.
float ALAutonomousLifeProxy::getRobotOffsetFromFloor()

Retrieves the current offset of the robot from the floor.

The default offset is 0.

Returns:A float value in meters.
void ALAutonomousLifeProxy::setSafeguardEnabled(const std::string& name, const bool& enabled)

Sets if a given safeguard will be handled by Autonomous Life or not. Default for all safeguards is true.

These parameters are automatically reset to default at the end of each activity.

Parameters:
  • name – Name of the safeguard to consider: RobotPushed, RobotFell, RobotMoved, CriticalDiagnosis, CriticalTemperature
bool ALAutonomousLifeProxy::isSafeguardEnabled(const std::string& name)

Checks if a given safeguard will be handled by Autonomous Life or not. Default for all safeguards is true.

Parameters:
  • name – Name of the safeguard to consider: RobotPushed, RobotFell, RobotMoved, CriticalDiagnosis, CriticalTemperature
Returns:

A bool, true if Autonomous Life handles the safeguard.
std::string ALAutonomousLifeProxy::focusedActivity()

Retrieves the current focused activity.

Returns:The name of the focused activity. Is an empty string (“”) if no activity is focused.
void ALAutonomousLifeProxy::switchFocus()

There are two overloads of this function:

int ALAutonomousLifeProxy::switchFocus(const std::string& activity_name)

The focused activity is the one running activity. This has the same effect as calling switchFocus(activity_name, 0)

Parameters:
  • activity_name –

    The name of the activity to start and switch focus to.

    The current focused activity is stopped first.

    Format: “package-uuid/behavior-path”
int ALAutonomousLifeProxy::switchFocus(const std::string& activity_name, const int& flags)

The focused activity is the one running activity.

This function allows to use the stacking feature of activity focus.

Parameters:
  • activity_name –

    The name of the activity to start and switch focus to.

    The current focused activity is stopped first.

    Format: “package-uuid/behavior-path”

  • flags –

    STOP_CURRENT(0) or STOP_AND_STACK_CURRENT(1).

    If STOP_AND_STACK_CURRENT is used, then the current focused activity will remain on the stack. When the newly focused activity is stopped, the previous one in the stack will automatically be restarted and regain focus.
void ALAutonomousLifeProxy::stopFocus()

This will stop the focused activity.

If there is a previous activity remaining on the stack, it is restarted and focused.

See switchFocus() and STOP_AND_STACK_CURRENT to see how to leave activities on the stack when switching focus.

void ALAutonomousLifeProxy::stopAll()

This will stop the focused activity.

It will also clear the stack; no stacked activities will automatically be restarted and focused.

See switchFocus() and STOP_AND_STACK_CURRENT to see how to leave activities on the stack when switching focus.

int ALAutonomousLifeProxy::getLifeTime()

Gets the time in seconds as life sees it. Based on gettimeofday().

Returns:The int time in seconds as Autonomous Life sees it.
AL::ALValue ALAutonomousLifeProxy::getActivityStatistics()

Gets focus count, last focused time, etc for each activity.

Times based on getLifeTime()

Returns:A map of activity names, with a corresponding map of “prevFocusTime”, “prevUnfocusTime”, “focusCount”, “totalDuration”. Times are 0 for unlaunched Activities.
AL::ALValue ALAutonomousLifeProxy::getAutonomousActivityStatistics()

Gets focus count, last focused time, etc just for each autonomous activity. This returns a subset of what ALAutonomousLifeProxy::getActivityStatistics returns. An autonomous activity is one that has launch trigger conditions.

Times based on getLifeTime()

Returns:A map of activity names, with a corresponding map of “prevFocusTime”, “prevUnfocusTime”, “focusCount”, “totalDuration”. Times are 0 for unlaunched Activities.
AL::ALValue ALAutonomousLifeProxy::getFocusHistory()

There are two overloads of this function. It is recommended to specify maximum depth to prevent large ALValues from being transmitted.

AL::ALValue ALAutonomousLifeProxy::getFocusHistory()

Gets a list of the activities that have been focused, and their time focused, sorted from oldest to most recent.

Times based on getLifeTime()

Returns:A list of pairs, each pair is ActivityName, PreviousFocusedTime.
AL::ALValue ALAutonomousLifeProxy::getFocusHistory(const int& depth)

Gets a list of the activities that have been focused, and their time focused, sorted from oldest to most recent.

Times based on getLifeTime()

Parameters:
  • depth – The maximum size of a subset of history to return. The subset is of the most recent history.
Returns:

A list of pairs, each pair is ActivityName, PreviousFocusedTime.
AL::ALValue ALAutonomousLifeProxy::getStateHistory()

There are two overloads of this function. It is recommended to specify maximum depth to prevent large ALValues from being transmitted.

AL::ALValue ALAutonomousLifeProxy::getStateHistory()

Gets a list of the states that have been entered, and their time entered, sorted from oldest to most recent.

Times based on getLifeTime()

Returns:A list of pairs, each pair is StateName, PreviousEnteredTime.
AL::ALValue ALAutonomousLifeProxy::getStateHistory(const int& depth)

Gets a list of the states that have been entered, and their time entered, sorted from oldest to most recent.

Times based on getLifeTime()

Parameters:
  • depth – The maximum size of a subset of history to return. The subset is of the most recent history.
Returns:

A list of pairs, each pair is StateName, PreviousEnteredTime.
std::string ALAutonomousLifeProxy::getActivityNature(const std::string& activity_name)

Tells you if an activity has “interactive” or “solitary” nature.

If you pass a string which is not an activity, this will throw.

Parameters:
  • activity_name –

    The name of the activity to query.

    Format: “package-uuid/behavior-path”
Returns:

“interactive” or “solitary”
std::string ALAutonomousLifeProxy::getActivityContextPermissionViolations(const std::string& activity_name)

Gets a list of permissions that would be violated by a given activity in the current context.

Parameters:
  • activity_name –

    The name of the activity to query.

    Format: “package-uuid/behavior-path”
Returns:

An array of strings of the violated permissions.

“nature”: If the activity is solitary but Autonomous Life is in interactive state.

“canRunOnPod”: If the robot is currently on the Charging Station, but the activity does not claim that it can be started on the Charging Station in its properties.

“canRunInSleep”: If the robot is currently asleep, the activity cannot be started.

“error”: If the passed activity name is not actually an activity.
AL::ALValue ALAutonomousLifeProxy::getFocusContext(const std::string& key_name)

Gets a value of an ALMemory key that is used in an activity launch trigger condition. The returned value will reflect the value at the time of the most recent autonomous activity focus. Use this to understand why an activity was started autonomously. Times based on getLifeTime()

Parameters:
  • key_name –

    The name of the ALMemory key to query.

    If the passed key is not used in any conditions, the function will throw
Returns:

A list of the timestamp of when it was set and the ALValue of the memory key: [seconds, microseconds, value]
void ALAutonomousLifeProxy::setAutonomousAbilityEnabled(const std::string& autonomous_ability, bool enabled)

Enables or disables a specific autonomous ability or all of them.

Parameters:
  • autonomous_ability – The autonomous ability to enable/disable (ex: “BasicAwareness”) or “All” if you want to enable or disable all the autonomous abilities.
  • enabled – True to enable the autonomous ability, False otherwise.

For further details, see: Autonomous Abilities.

bool ALAutonomousLifeProxy::getAutonomousAbilityEnabled(const std::string& autonomous_ability)

Returns whether an autonomous ability is enabled.

Parameters:
  • autonomous_ability – The autonomous ability (ex: “BasicAwareness”) or “All” (in this case it will return True only if all the autonomous abilities are enabled).
Returns:

True if enabled, False otherwise.

For further details, see: Autonomous Abilities.

std::vector<AutonomousAbilityStatus> ALAutonomousLifeProxy::getAutonomousAbilitiesStatus()

Returns the status of all the autonomous abilities.

Returns:A vector of AutonomousAbilityStatus containing the autonomous ability name, a boolean to know if the autonomous ability is enabled or not and another boolean to know if the autonomous ability is currently running or not. 
AutonomousAbilityStatus =
{
   "name" : <str>,
   "enabled" : <bool>,
   "running" : <bool>
}

For further details, see: Priority between the Autonomous Abilities.

Events

Event: "AutonomousLife/State"
callback(std::string eventName, std::string state, std::string subscriberIdentifier)

Raised when the state of autonomous life changes.

Note that if one interactive activity switches focus to another interactive activity, this event is raised, as the “interactive” state is being reasserted.

This event is raised after Autonomous Life has completed all necessary internal operations to prepare for the state.

Parameters:
  • eventName (std::string) – “AutonomousLife/State”
  • state – The current state of Autonomous Life. Can be one of the States.
  • subscriberIdentifier (std::string) –
Event: "AutonomousLife/FocusedActivity"
callback(std::string eventName, std::string activity_name, std::string subscriberIdentifier)

Raised whenever the focused activity changes.

Parameters:
  • eventName (std::string) – “AutonomousLife/FocusedActivity”
  • activity_name – The name of the focused activity. If no activity is focused it is an empty string: “”
  • subscriberIdentifier (std::string) –
Event: "AutonomousLife/CompletedActivity"
callback(std::string eventName, std::string activity_name, std::string subscriberIdentifier)

Raised whenever an activity completes its execution and exits.

Note This event is raised before the FocusedActivity event.

Parameters:
  • eventName (std::string) – “AutonomousLife/CompletedActivity”
  • activity_name – The name of the previous activity that exited.
  • subscriberIdentifier (std::string) –
Event: "AutonomousLife/NextActivity"
callback(std::string eventName, std::string activity_name, std::string subscriberIdentifier)

Raised whenever an activity is going to be focused.

Note This event is raised before the FocusedActivity event.

Parameters:
  • eventName (std::string) – “AutonomousLife/NextActivity”
  • activity_name – The name of the activity that will be focused next.
  • subscriberIdentifier (std::string) –
Event: "AutonomousLife/LaunchSuggestions"
callback(std::string eventName, std::vector<std::string> activity_names, std::string subscriberIdentifier)

Raised whenever there are activities that have launch conditions triggered.

Parameters:
  • eventName (std::string) – “AutonomousLife/LaunchSuggestions”
  • activity_names – The list of activities that currently have their launch conditions triggered.
  • subscriberIdentifier (std::string) –

Signals

ActivityTransitionInfo ALAutonomousLifeProxy::activityTransition()
Triggered:When life switches focus from one activity to another.
Returns:A data structure explaining the when, what, and why of the focus transition. 
ActivityTransitionInfo =
{
  "TransitionTime" : <qi::SystemClock>,
  "PreviousActivityName" : <string>,
  "PreviousActivityStopReason" : <string>,
  "FocusedActivityName" : <string>,
  "FocusedActivityStartReason" : <string>
}

The PreviousActivityName and FocusedActivityName are formatted the same as ALAutonomousLifeProxy::switchFocus.

For more information about system clock, see: qi clocks.

FocusedActivityStartReason:

Value Description
default-activity The default case happens when life transitions from disabled/safeguard state.
condition Activity started because its trigger condition was true.
applauncher-voice Activity started by voice in main interactive activity.
applauncher-tablet Activity started by tablet in main interactive activity.
unstacked Activity started because it was on the activity stack, and top of stack exited
unknown-api-caller Activity started by a call to switchFocus() API with no reason given.

PreviousActivityStopReason:

Value Description
self-stop Activty exited by its self.
user-stop User stopped the activity with the head tactile gesture.
users-lost The main interactive activity exited because no users were present.
disabled-state, safeguard-state Activity was terminated because of entering disabled/safeguard states.
permission-context Activity was terminated due to a permission context change that is incompatible. For example, if the robot is put to sleep.
switchfocus-api-interrupt The switchFocus() API was used, which terminates the previous activity before starting the next one.
unknown-api-caller The stopFocus/stopAll() API was called with no reason given.